diff --git a/ads/concepts/breaks.mdx b/ads/concepts/breaks.mdx index 6f03eb0f9298..1bbc6e7d87c7 100644 --- a/ads/concepts/breaks.mdx +++ b/ads/concepts/breaks.mdx @@ -402,6 +402,8 @@ A `static` asset is a media resource the player retrieves directly — a video o } ``` +See [Static assets](../player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx) for the supported creative formats and layouts in the OptiView Ads SDK. + #### VAST assets A `vast` asset points to an ad server that responds with a VAST XML document describing how the ad should be played. The `uri` is the VAST tag URL, and the `mimeType` should be `application/xml` or `text/xml`: @@ -415,6 +417,8 @@ A `vast` asset points to an ad server that responds with a VAST XML document des } ``` +A `vast` asset can also carry `assetParameters`, which the player appends to the VAST tag URL as query parameters. See [VAST](../player-integration/optiview-ads-sdk/ad-workflows/vast.mdx) for how the OptiView Ads SDK plays VAST tags, and the layouts they support. + #### Vendor assets A `vendor` asset is delivered through an [ad vendor integration](../integrations/index.mdx), such as Google Ad Manager. The vendor decides the ad content; you identify the vendor and pass the vendor-specific parameters: diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 422eef8d56f2..e1a6a3372a44 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -84,9 +84,11 @@ await sdk.startSession({ Follow the platform guide for [Web](/ads/player-integration/optiview-ads-sdk/web), [Android](/ads/player-integration/optiview-ads-sdk/android), [iOS](/ads/player-integration/optiview-ads-sdk/ios), or [React Native](/ads/player-integration/optiview-ads-sdk/react-native). If you use the OptiView Player, the legacy [OptiView Player integration](/ads/player-integration/optiview-player/) is also available. +This integration plays every [ad workflow](/ads/player-integration/optiview-ads-sdk/#ad-workflows): static assets from your CDN, VAST tags from your ad server, and Google Pod Serving. Static assets need nothing more; for VAST or Google Pod Serving on Web, the workflow page lists the Google IMA script to add to your page. + ## 4. Schedule a break -A [break](/ads/concepts/breaks) describes an ad opportunity: when it starts, how long it lasts, and which ad experience plays. The simplest break plays a single full-screen ad from a VAST tag. +A [break](/ads/concepts/breaks) describes an ad opportunity: when it starts, how long it lasts, and which ad experience plays. The simplest break plays a single full-screen video ad from your CDN, as a [static asset](/ads/player-integration/optiview-ads-sdk/ad-workflows/static-assets). Dashboard: open the channel → **Breaks → Schedule now**. Or via the API, scheduling a 30-second break a few minutes from now: @@ -102,16 +104,18 @@ curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels//bre "format": "single", "assets": [ { - "type": "vast", + "type": "static", "mediaType": "video", - "uri": "https://cdn.example.com/vast.xml" + "uri": "https://cdn.example.com/ads/spot.m3u8" } ] } }' ``` -Replace `` with an ISO 8601 UTC timestamp a few minutes in the future, for example `2026-01-01T12:00:00.000Z`. +Replace `` with an ISO 8601 UTC timestamp a few minutes in the future, for example `2026-01-01T12:00:00.000Z`, and the `uri` with the URL of an ad video on your CDN. + +To let an ad server choose the ad instead, use a [VAST](/ads/player-integration/optiview-ads-sdk/ad-workflows/vast) asset or [Google Pod Serving](/ads/player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving). Once you schedule breaks regularly, [templates](/ads/concepts/templates) let you preconfigure the break payload so scheduling becomes a one-liner. @@ -121,16 +125,17 @@ Start playback of your stream on your device. Shortly before the scheduled start You can follow along on both sides: -- **In the dashboard or API:** the break's [lifecycle status](/ads/concepts/breaks#break-lifecycle) moves from `PREPARING` to `READY`, and to `SIGNALED` once it is announced to players. +- **In the dashboard or API:** the break's [lifecycle status](/ads/concepts/breaks#break-lifecycle) is `READY` (a Google pod break passes through `PREPARING` first), and moves to `SIGNALED` once it is announced to players. - **In the player:** the ad plays at the scheduled time and your content resumes afterwards. If the break does not play, verify that the Break Manifest URL from step 2 returns the break, and that your stream carries the time metadata required by the channel's timebase. ## Next steps -| Resource | Description | -| ------------------------------------------------------------- | ----------------------------------------------------------------- | -| [Player integration](/ads/player-integration/) | The full integration guides for the SDK and the OptiView Player. | -| [Breaks](/ads/concepts/breaks) | Everything a break can do: layouts, variants, controls, punching. | -| [Origins and Break Detection](/ads/concepts/marker-detection) | Turn the ad markers in your stream into breaks automatically. | -| [Google Ad Manager](/ads/integrations/google/) | Let Google Ad Manager decision the ads that fill your breaks. | +| Resource | Description | +| ---------------------------------------------------------------------- | ----------------------------------------------------------------- | +| [Player integration](/ads/player-integration/) | The full integration guides for the SDK and the OptiView Player. | +| [Ad workflows](/ads/player-integration/optiview-ads-sdk/#ad-workflows) | Static assets, VAST, and Google Pod Serving with the SDK. | +| [Breaks](/ads/concepts/breaks) | Everything a break can do: layouts, variants, controls, punching. | +| [Origins and Break Detection](/ads/concepts/marker-detection) | Turn the ad markers in your stream into breaks automatically. | +| [Google Ad Manager](/ads/integrations/google/) | Let Google Ad Manager decision the ads that fill your breaks. | diff --git a/ads/how-to-guides/ad-tag-parameters.mdx b/ads/how-to-guides/ad-tag-parameters.mdx index 3da2b4206c5c..1ec7c70f33a6 100644 --- a/ads/how-to-guides/ad-tag-parameters.mdx +++ b/ads/how-to-guides/ad-tag-parameters.mdx @@ -4,13 +4,30 @@ sidebar_position: 3 # Ad targeting parameters -When an ad server such as Google Ad Manager decisions a break, you can pass key-value parameters with the request to personalize the ads — for example the content genre, the placement type, or custom targeting values. In OptiView Ads, these parameters are called **`assetParameters`**. For Google, they map directly to the [ad tag parameters](https://support.google.com/admanager/answer/10678356) (`adTagParameters`) on the ad request. +When an ad server decides which ad fills a break, you can pass key-value parameters with the ad request to personalize the ads — for example the content genre, the placement type, or custom targeting values. In OptiView Ads, these parameters are called **`assetParameters`**. How they reach the ad server depends on the [ad workflow](../player-integration/optiview-ads-sdk/index.mdx#ad-workflows): -You can set `assetParameters` in two places: on the break in the **backend**, and in the **OptiView Ads SDK** on the client. Client-side values overwrite the backend values when the same key is set in both. +- **[VAST](../player-integration/optiview-ads-sdk/ad-workflows/vast.mdx):** the SDK appends them to the VAST tag URL as URL-encoded query parameters. +- **[Google Pod Serving](../player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx):** they are sent to Google as [ad tag parameters](https://support.google.com/admanager/answer/10678356) (`adTagParameters`). +- **[Static assets](../player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx)** involve no ad request, so they do not use `assetParameters`. + +You can set `assetParameters` in two places: on the break in the **backend**, and in the **OptiView Ads SDK** on the client. ## Asset parameters in the backend -When you [schedule a break](../concepts/breaks.mdx#scheduling) with a vendor asset, you can add an `assetParameters` map to the asset: +When you [schedule a break](../concepts/breaks.mdx#scheduling) with a VAST or vendor asset, you can add an `assetParameters` map to the asset. For a VAST asset: + +```json +{ + "type": "vast", + "mediaType": "video", + "uri": "https://adserver.example.com/vast?slot=midroll", + "assetParameters": { + "content_genre": "sports" + } +} +``` + +For a Google Pod Serving vendor asset: ```json { @@ -26,22 +43,24 @@ When you [schedule a break](../concepts/breaks.mdx#scheduling) with a vendor ass } ``` -OptiView Ads forwards these parameters to the ad server when the break is announced, and also delivers them to the player through the [Break Manifest](../concepts/break-manifest.mdx) so they are included on the ad request. See [Google Pod Serving](../integrations/google/pod-serving.mdx#required-google-parameters) for the parameters Google requires. +OptiView Ads delivers these parameters to the player through the [Break Manifest](../concepts/break-manifest.mdx), so they are included on the ad request. For Google, they are also forwarded to Google when the break is announced; see [Google Pod Serving](../integrations/google/pod-serving.mdx#required-google-parameters) for the parameters Google requires. -## Overwriting from the OptiView Ads SDK +## Asset parameters in the OptiView Ads SDK -The OptiView Ads SDK can supply its own `assetParameters` and overwrite the backend values. There are two client-side layers: +The OptiView Ads SDK can add its own `assetParameters`. There are two client-side layers: - **Session parameters** — passed to `startSession()`, they apply to every break in the session. - **Live updates** — passed to `updateAssetParameters()` during an active session, for values that change while the viewer is watching. -The three layers are merged **per key**, from lowest to highest precedence: +## How the layers are merged -1. The break's `assetParameters` from the backend. -2. The session's `assetParameters` from `startSession()`. -3. The latest `updateAssetParameters()` call. +The layers are merged **per key**, from lowest to highest precedence: -Overwriting one key never discards the others, and live updates apply to **future** breaks only: a break whose ad request has already been sent cannot be retargeted. +1. The session's `assetParameters` from `startSession()`. +2. The latest `updateAssetParameters()` call. +3. The break's `assetParameters` from the backend. + +A value set on the break wins over the same key set in the SDK, so set each key in one place only. Overwriting one key never discards the others, and live updates apply to **future** breaks only: a break whose ad request has already been sent cannot be retargeted. ## Backend or client? @@ -50,6 +69,20 @@ As a rule of thumb: - **Set through the backend** the values that describe the break or the content and are the same for every viewer — such as `description_url`, the placement declaration, and campaign or content targeting that is known when the break is scheduled. - **Set through the SDK** the values that depend on the viewer, the device, or the moment of playback — such as device identifiers, consent state, autoplay/mute state (`vpa`, `vpmute`), or audience context that changes during the session. +## Macros + +A parameter value can contain macros: `$NAME$` tokens that the SDK replaces when it builds the ad request. Macros let a value on the break carry information that is only known on the device. The SDK provides these built-in macros: + +| Macro | Value | +| ----------------------------------- | ---------------------------------------------------------------------------- | +| `$OPTIVIEW_PLAYER_WIDTH$` | Width of the ad container, in logical pixels. | +| `$OPTIVIEW_PLAYER_HEIGHT$` | Height of the ad container, in logical pixels. | +| `$OPTIVIEW_BREAK_DURATION_SECONDS$` | Duration of the ad, in seconds: the asset's `duration`, else the break's. | +| `$OPTIVIEW_BREAK_DURATION_MS$` | The same duration, in whole milliseconds. | +| `$OPTIVIEW_USER_AGENT$` | The user agent of the device. Not available on iOS; register your own value. | + +For example, `"size": "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$"` is sent as `size=1920x1080`. You can register your own macros, or override a built-in one, with `assetParameterMacros` in the session configuration. Tokens the SDK does not know, such as `$PUBLISHER_ID$`, are sent unchanged, so your ad server can still expand its own macros. See `SessionConfig` in the API reference of your platform for the details. + ## Platform examples The examples below start a session with session-level `assetParameters` and update them mid-session. See the [OptiView Ads SDK](../player-integration/optiview-ads-sdk/index.mdx) documentation for the full integration. @@ -118,8 +151,10 @@ ads.updateAssetParameters({ cust_params: 'sport=basketball' }); ## Related resources -| Resource | Description | -| -------------------------------------------------------------------- | ----------------------------------------------- | -| [Google Pod Serving](../integrations/google/pod-serving.mdx) | Required Google parameters and pod decisioning. | -| [Breaks](../concepts/breaks.mdx) | Scheduling breaks with vendor assets. | -| [OptiView Ads SDK](../player-integration/optiview-ads-sdk/index.mdx) | Integrating the SDK with your player. | +| Resource | Description | +| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | +| [VAST](../player-integration/optiview-ads-sdk/ad-workflows/vast.mdx) | Playing VAST tags with the SDK. | +| [Google Pod Serving with the SDK](../player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx) | Playing Google pods with the SDK. | +| [Google Pod Serving](../integrations/google/pod-serving.mdx) | Required Google parameters and pod decisioning. | +| [Breaks](../concepts/breaks.mdx) | Scheduling breaks with VAST and vendor assets. | +| [OptiView Ads SDK](../player-integration/optiview-ads-sdk/index.mdx) | Integrating the SDK with your player. | diff --git a/ads/integrations/google/pod-serving.mdx b/ads/integrations/google/pod-serving.mdx index 3d0d39accd80..dbe488627780 100644 --- a/ads/integrations/google/pod-serving.mdx +++ b/ads/integrations/google/pod-serving.mdx @@ -77,7 +77,7 @@ Google performs the decisioning, so no asset URI is needed: once Google has deci The optional `assetParameters` map contains the [Google ad tag parameters](https://support.google.com/admanager/answer/10678356) (`adTagParameters`) for the break. OptiView Ads forwards them to Google when the break is announced, and delivers them to the player through the Break Manifest so they are included on the pod request. -Players can extend these parameters: the OptiView player SDKs accept `adTagParameters` on the ad description (`TheoAdDescription`). When the same parameter is set both on the break and on the player, the player-side value wins. See [Ad tag parameters](../../how-to-guides/ad-tag-parameters.mdx) for the player-side API on each platform. +Players can extend these parameters. The OptiView Ads SDK accepts `assetParameters` in its session configuration; when the same parameter is set both on the break and in the SDK, the break's value wins. See [Ad targeting parameters](../../how-to-guides/ad-tag-parameters.mdx) for the SDK API on each platform. The legacy OptiView Player SDKs accept `adTagParameters` on the ad description (`TheoAdDescription`); there, the player-side value wins. As a rule of thumb: @@ -147,12 +147,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.mdx) | Passing ad tag parameters from the player. | -| [Player integration](../../player-integration/index.mdx) | Set up a player with pod serving. | +| 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.mdx) | Passing ad tag parameters from the player. | +| [Google Pod Serving with the SDK](../../player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx) | Set up the OptiView Ads SDK in your app for pod serving. | diff --git a/ads/integrations/index.mdx b/ads/integrations/index.mdx index 13f2eb75c1a6..fb75ec917ad9 100644 --- a/ads/integrations/index.mdx +++ b/ads/integrations/index.mdx @@ -7,6 +7,8 @@ sidebar_label: Integrations An integration connects OptiView Ads to an ad decisioning or "pod" serving vendor. Vendors are supported by providing [assets of type Vendor](../concepts/breaks.mdx#vendor-assets) in a break variant: the vendor makes the ad decisions, and OptiView Ads delivers the result to players. [Google Ad Manager 360](./google/index.mdx) is the first supported integration. +You do not need an integration to play [static assets](../player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx) from your CDN or [VAST](../player-integration/optiview-ads-sdk/ad-workflows/vast.mdx) tags from your own ad server: those breaks work on any channel. + ## Supported vendors | Vendor | Enum value | Delivery | diff --git a/ads/player-integration/index.mdx b/ads/player-integration/index.mdx index f17182f6b40b..9a363f72d61f 100644 --- a/ads/player-integration/index.mdx +++ b/ads/player-integration/index.mdx @@ -9,7 +9,7 @@ To play the ad breaks you schedule with OptiView Ads, your application needs a p ## 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. +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, and plays every [ad workflow](./optiview-ads-sdk/index.mdx#ad-workflows): static assets, VAST tags, and Google Pod Serving. This is the recommended path for any new integration. diff --git a/ads/player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx b/ads/player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx new file mode 100644 index 000000000000..07a0d2fd40d7 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving.mdx @@ -0,0 +1,120 @@ +--- +sidebar_position: 3 +sidebar_label: Google Pod Serving +--- + +# Google Pod Serving + +With Google Pod Serving, Google Ad Manager decides which ads fill each break. OptiView Ads announces upcoming breaks to Google, Google assembles the ads into a pod, and the SDK plays the pod when the break starts. Use this workflow when you sell your inventory through Google Ad Manager 360. + +This page covers your app. Setting up Google Ad Manager, configuring the channel, and scheduling pod breaks are described in [Google Pod Serving](../../../integrations/google/pod-serving.mdx) in the Integrations section. + +## Before you start + +- The [Google Ad Manager prerequisites](../../../integrations/google/index.mdx) are in place for your organization. +- Your channel is [configured for Google Pod Serving](../../../integrations/google/pod-serving.mdx#configure-your-channel) with the custom asset key of your Google live stream. + +## What your app needs + +The SDK reads the Google settings — your network code and the channel's custom asset key — from the channel's Break Manifest, and starts the Google stream session automatically when the session starts. You do not configure them in the app, so your app and the backend always agree on which Google live stream the pods belong to. + +| Platform | Requirement | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Web | Load Google's IMA DAI SDK on the page, before your application script (see below). | +| Android | Nothing extra: the SDK runtime includes the Google IMA SDK. | +| iOS and tvOS | Nothing extra: the runtime pod includes the Google IMA SDK. With Swift Package Manager, add the Google IMA packages as described in [iOS](../ios.mdx#swift-package-manager). | +| React Native | Nothing extra: the native SDKs include the Google IMA SDK. | + +On Web, add the IMA DAI loader to your page: + +```html + +``` + +If your channel also uses [VAST](./vast.mdx) breaks, load `ima3.js` as well; the two scripts work side by side. + +:::note[Upgrading from an earlier integration] +Earlier versions of this guide set a `networkCode` in the `gam` configuration and a `customAssetKey` in the session configuration. The SDK no longer accepts them: remove both, and the SDK takes the values from the Break Manifest. +::: + +### Turn Google off for a session + +To keep Google out of a session — for example until the viewer gives consent, or in a build that must not contact Google — set `enabled` to `false` in the `gam` configuration. The SDK then skips the Google breaks in that session and reports `DA-GAM-CONFIG-MISSING`. + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```typescript +const sdk = new OptiViewAds({ + player: new THEOplayerAdapter(player, container), + container: document.getElementById('container'), + gam: { enabled: false }, +}); +``` + + + + +```kotlin +val sdk = OptiViewAds( + config = OptiViewAdsConfig( + player = THEOplayerAdapter(theoPlayerView.player), + gam = GamConfig(enabled = false), + ), + renderer = OverlayAdRenderer(adContainer), +) +``` + + + + +```swift +let sdk = OptiViewAds( + config: OptiViewAdsConfig( + player: THEOplayerAdapter(player: theoplayer), + gam: GamConfig(enabled: false) + ), + renderer: OverlayAdRenderer(container: adContainer) +) +``` + + + + +```typescript +const ads = createOptiViewAds(player, { gam: { enabled: false } }); +``` + + + + +## Ad targeting parameters + +For Google, `assetParameters` are sent as Google [ad tag parameters](https://support.google.com/admanager/answer/10678356) (`adTagParameters`). As a rule of thumb: + +- Set the values that describe your content on the break, such as `description_url` and `plcmt`. See [Required Google parameters](../../../integrations/google/pod-serving.mdx#required-google-parameters). +- Set the values that depend on the playback environment in the SDK, such as `vpa` and `vpmute` and, in apps, the [device and app identity parameters](../../../integrations/google/pod-serving.mdx#additional-parameters-for-app-inventory). + +When the same key is set in both places, the value on the break wins. See [Ad targeting parameters](../../../how-to-guides/ad-tag-parameters.mdx) for the merge rules and platform examples. + +## Troubleshooting + +| Diagnostic | What it means | What to do | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | +| `DA-GAM-CONFIG-RESOLVED` | Informational: the Google stream session uses the network code and custom asset key in the diagnostic. | Check that they match your Google live stream. | +| `DA-GAM-CONFIG-MISSING` | The Break Manifest carries Google breaks but no usable Google configuration, or Google is turned off with `gam` `enabled: false`. | Check that the channel is configured for Google Pod Serving, or remove the opt-out. | +| `DA-GAM-SESSION-FAILED` | The Google stream session could not be started. | On Web, load `ima3_dai.js` on the page. Otherwise, check the error message in the diagnostic. | + +Breaks that fail in the backend, for example because Google could not decision them in time, end up in the `ERROR` state and never reach the SDK. See [Troubleshooting](../../../integrations/google/pod-serving.mdx#troubleshooting) on the Google Pod Serving integration page. + +## Related resources + +| Resource | Description | +| ------------------------------------------------------------------------------ | ------------------------------------------------------------------- | +| [Google Ad Manager](../../../integrations/google/index.mdx) | Organization-level prerequisites: network code and service account. | +| [Google Pod Serving integration](../../../integrations/google/pod-serving.mdx) | Google Ad Manager setup, channel configuration, and pod breaks. | +| [Ad targeting parameters](../../../how-to-guides/ad-tag-parameters.mdx) | Passing ad tag parameters to Google. | +| [VAST](./vast.mdx) | Play VAST tags from your own ad server, without Google Ad Manager. | diff --git a/ads/player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx b/ads/player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx new file mode 100644 index 000000000000..1ca503b0d446 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/ad-workflows/static-assets.mdx @@ -0,0 +1,84 @@ +--- +sidebar_position: 1 +sidebar_label: Static assets +--- + +# Static assets + +With static assets, each break points directly at its ad creatives: video or image files that you host on your own CDN. No ad server is involved — the SDK fetches the creative from the URL on the break and plays it when the break starts. Use this workflow for direct-sold campaigns, sponsorships, promos, and branded overlays where you already know which creative to show. + +## What your app needs + +Nothing beyond the integration for your platform: [Web](../web.mdx), [Android](../android.mdx), [iOS](../ios.mdx), or [React Native](../react-native.mdx). Static assets need no ad server, no Google Ad Manager account, and no extra configuration in the app. + +## Schedule a break with static assets + +A static asset sets `type` to `static` and `uri` to the URL of the creative: + +```bash +curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels//breaks' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: ' \ + -d '{ + "start": "", + "duration": 30, + "variant": { + "format": "single", + "assets": [ + { + "type": "static", + "mediaType": "video", + "mimeType": "application/x-mpegurl", + "uri": "https://cdn.example.com/ads/spot.m3u8", + "interaction": { "clickThrough": "https://www.example.com/offer" } + } + ] + } + }' +``` + +The `uri` can also be a list of URLs targeted per device type. See [Static assets](../../../concepts/breaks.mdx#static-assets) and [Asset URI targeting](../../../concepts/breaks.mdx#asset-uri-targeting) for the full asset model. + +## Supported layouts + +Static assets work in every [layout](../../../concepts/breaks.mdx#layouts) and as [pause ads](../../../concepts/breaks.mdx#pause): + +| Layout | Static asset | +| --------------------- | ---------------------------------------------------------------------------------------- | +| `single` | A video that replaces the content. | +| `double`, `lshape_ad` | A video, with an image or video `companion` that fills the background. | +| `lshape_content` | An image that fills the L-shaped backdrop while your content keeps playing. | +| `overlay` | An image or video on top of your content. | +| Pause ad | An image, or a progressive MP4 video that plays muted, shown while the viewer is paused. | + +An image stays on screen for the asset's `duration`, or for the break's `duration` when the asset has none. + +## Creative formats + +- **HLS (`.m3u8`)** is the recommended format for video creatives on every platform. On connected TVs in particular, the SDK can prefetch an HLS creative ahead of the break, so the ad starts faster. +- **Progressive MP4** also works. On Web, the SDK plays MP4 creatives through the browser's own video element. +- **Images** are used for overlays, companions, L-shape backdrops, and pause ads. + +Set `mimeType` on the asset when you know it. The SDK then knows upfront how to play the creative, instead of having to find out, which makes ad preparation faster. + +## Tracking and reporting + +The SDK reports an OptiView Ads [impression](../../../how-to-guides/ad-impressions.md) for every break it presents, and emits ad events — such as the start and end of each break and ad — that your app can listen to. See the API reference of your platform for the full list of events. + +Static assets carry no third-party tracking URLs. If an advertiser needs to count impressions in their own ad server, deliver the creative through a [VAST](./vast.mdx) tag instead: the VAST response carries the advertiser's tracking URLs, which are fired while the ad plays. + +## Troubleshooting + +- **The break does not play.** Check that the channel's [Break Manifest](../../../concepts/break-manifest.mdx) contains the break, and that the creative URL is publicly reachable. +- **Web: the creative fails to load.** The SDK downloads HLS creatives with HTTP requests from your page, so your CDN must allow cross-origin requests (CORS) from your app's origin. +- **A creative cannot be played.** The SDK emits an `aderror` event for the asset, continues with the next asset in the break if there is one, and otherwise returns to your content. + +## Related resources + +| Resource | Description | +| ------------------------------------------------------------------ | ------------------------------------------------------------- | +| [Breaks](../../../concepts/breaks.mdx) | Layouts, variants, controls, and the asset model. | +| [Templates](../../../concepts/templates.mdx) | Store a break with its static assets once, and reuse it. | +| [VAST](./vast.mdx) | Let your ad server decide which creative to play. | +| [Ad impression tracking](../../../how-to-guides/ad-impressions.md) | How OptiView Ads counts the breaks presented to your viewers. | diff --git a/ads/player-integration/optiview-ads-sdk/ad-workflows/vast.mdx b/ads/player-integration/optiview-ads-sdk/ad-workflows/vast.mdx new file mode 100644 index 000000000000..eb3cee210285 --- /dev/null +++ b/ads/player-integration/optiview-ads-sdk/ad-workflows/vast.mdx @@ -0,0 +1,115 @@ +--- +sidebar_position: 2 +sidebar_label: VAST +--- + +# VAST + +With VAST, each break points at a VAST tag: a URL on your ad server, or an advertiser's, that returns a [VAST](https://iabtechlab.com/standards/vast/) XML document. The ad server decides which creative to play, and its response carries the media files and the tracking URLs. Use this workflow when you run your own ad server, or buy from partners that deliver their ads through VAST tags. + +The SDK requests and plays VAST tags on the device, through Google's client-side IMA SDK. IMA processes the VAST response — it follows wrappers, picks a media file, and fires the tracking URLs. IMA works with any VAST-compliant ad server: you do not need a Google Ad Manager account. + +## What your app needs + +| Platform | Requirement | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Web | Load Google's client-side IMA SDK on the page, before your application script (see below). | +| Android | Nothing extra: the SDK runtime includes the Google IMA SDK. | +| iOS and tvOS | Nothing extra: the runtime pod includes the Google IMA SDK. With Swift Package Manager, add the Google IMA packages as described in [iOS](../ios.mdx#swift-package-manager). | +| React Native | Nothing extra: the native SDKs include the Google IMA SDK. | + +On Web, add the IMA loader to your page: + +```html + +``` + +Without it, the SDK cannot play VAST breaks: it reports `DA-VAST-IMA-SDK-MISSING` and returns to your content. If your channel also uses [Google Pod Serving](./google-pod-serving.mdx), load `ima3_dai.js` as well; the two scripts work side by side. + +:::caution[Web: include an MP4 media file] +The IMA SDK for HTML5 plays the ad through the browser's own video element, which cannot play HLS outside Safari. Make sure your VAST responses include a progressive MP4 media file, or the ad fails to play in Chrome, Edge, and Firefox. +::: + +## Schedule a VAST break + +A VAST asset sets `type` to `vast` and `uri` to the VAST tag URL: + +```bash +curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels//breaks' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: ' \ + -d '{ + "start": "", + "duration": 30, + "variant": { + "format": "single", + "assets": [ + { + "type": "vast", + "mediaType": "video", + "mimeType": "application/xml", + "uri": "https://adserver.example.com/vast?slot=midroll", + "assetParameters": { + "content_genre": "sports" + } + } + ] + } + }' +``` + +The `uri` can also be a list of tag URLs targeted per device type. See [VAST assets](../../../concepts/breaks.mdx#vast-assets) and [Asset URI targeting](../../../concepts/breaks.mdx#asset-uri-targeting) for the full asset model. + +## Supported layouts + +VAST describes a linear (video) ad, so VAST assets work in the layouts where an ad video plays: + +| Layout | VAST asset | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `single` | Supported. | +| `double`, `lshape_ad` | Supported. The VAST ad plays in the ad box, and the asset's `companion` fills the background. | +| `lshape_content`, `overlay` | Not supported. The SDK does not play the asset and reports `DA-VAST-UNSUPPORTED-FORMAT`. Use a [static asset](./static-assets.mdx) instead. | +| Pause ad | Supported. The SDK reads the image from the VAST companion ads, or a progressive MP4 from the linear ad, and fires its impression tracking when shown. | + +VAST breaks play in server-guided sessions — the default `sgai` mode — only. + +## Ad targeting parameters + +To personalize the ad request, add `assetParameters`. The SDK appends them to the VAST tag URL as URL-encoded query parameters when it requests the tag. For the break above, with a session-level parameter `device_id` set in the SDK, the request becomes: + +```text +https://adserver.example.com/vast?slot=midroll&content_genre=sports&device_id=abc123 +``` + +Set the parameters in one of two places: + +- **On the break**, for values that are the same for every viewer, such as the content genre. +- **In the SDK**, with `assetParameters` in the session configuration or `updateAssetParameters()`, for values that depend on the viewer or the device. + +When the same key is set in both places, the value on the break wins. Parameter values can also contain macros, such as `$OPTIVIEW_PLAYER_WIDTH$`, that the SDK fills in when it builds the request. See [Ad targeting parameters](../../../how-to-guides/ad-tag-parameters.mdx) for the merge rules, the macros, and platform examples. + +## Tracking and reporting + +- IMA fires the tracking URLs in the VAST response, such as impressions, quartiles, and clicks, so the ad server counts the ad. +- The SDK reports an OptiView Ads [impression](../../../how-to-guides/ad-impressions.md) for the break, and emits the same ad events as for any other break. + +## Troubleshooting + +VAST failures never block your content: the SDK emits an `aderror` event, reports a diagnostic, and returns to the content. + +| Diagnostic | What it means | What to do | +| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `DA-VAST-IMA-SDK-MISSING` | Google's client-side IMA SDK is not available. | On Web, load `ima3.js` on the page. | +| `DA-VAST-IMA-ERROR` | IMA could not load, parse, or play the VAST response — for example an unreachable tag, an empty response, or no playable media file. | Test the tag in Google's [VAST Inspector](https://googleads.github.io/googleads-ima-html5/vsi/). On Web, make sure the response includes a progressive MP4 media file. | +| `DA-VAST-UNSUPPORTED-FORMAT` | The VAST asset is in an `overlay` or `lshape_content` break. | Use the `single`, `double`, or `lshape_ad` layout, or a static asset. | +| `DA-VAST-SSAI-UNSUPPORTED` | The VAST asset is in a server-side (SSAI) session. | Play VAST breaks in a server-guided (`sgai`) session. | + +## Related resources + +| Resource | Description | +| ----------------------------------------------------------------------- | ------------------------------------------------------------- | +| [Breaks](../../../concepts/breaks.mdx) | Layouts, variants, controls, and the asset model. | +| [Ad targeting parameters](../../../how-to-guides/ad-tag-parameters.mdx) | Passing targeting parameters to your ad server. | +| [Static assets](./static-assets.mdx) | Play creatives from your CDN without an ad server. | +| [Google Pod Serving](./google-pod-serving.mdx) | Let Google Ad Manager decision the ads that fill your breaks. | diff --git a/ads/player-integration/optiview-ads-sdk/android.mdx b/ads/player-integration/optiview-ads-sdk/android.mdx index 28c97d7d87ff..4eb4be9b7529 100644 --- a/ads/player-integration/optiview-ads-sdk/android.mdx +++ b/ads/player-integration/optiview-ads-sdk/android.mdx @@ -10,7 +10,7 @@ On Android and Android TV, the OptiView Ads SDK is a native Kotlin library that ## 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. +2. Check which [ad workflows](./index.mdx#ad-workflows) your breaks use. On Android, static assets, VAST, and Google Pod Serving all work with the installation below; nothing extra is needed. 3. Install the SDK together with the adapter for your player (see [Installation](#installation) and the player sections below). ## Installation @@ -27,7 +27,7 @@ dependencyResolutionManagement { } ``` -Then add the runtime to your app module. It brings in the core and SDK layers, Media3 and the Google IMA SDK transitively; replace `` with the SDK release you want to use: +Then add the runtime to your app module. It brings in the core and SDK layers, Media3, and the Google IMA SDK (used to play [VAST](./ad-workflows/vast.mdx) and [Google Pod Serving](./ad-workflows/google-pod-serving.mdx) breaks) transitively; replace `` with the SDK release you want to use: ```kotlin dependencies { diff --git a/ads/player-integration/optiview-ads-sdk/index.mdx b/ads/player-integration/optiview-ads-sdk/index.mdx index 75286c76d360..bc0b32d29087 100644 --- a/ads/player-integration/optiview-ads-sdk/index.mdx +++ b/ads/player-integration/optiview-ads-sdk/index.mdx @@ -17,6 +17,18 @@ The SDK is available for [Web](./web.mdx), [Android](./android.mdx), [iOS](./ios 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. +## Ad workflows + +The SDK plays whatever the breaks on your channel carry. Each [asset](../../concepts/breaks.mdx#asset-model) in a break uses one of three ad workflows, and one channel can mix them: + +| Workflow | What the break carries | What your app needs on top of the platform integration | +| ----------------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | +| [Static assets](./ad-workflows/static-assets.mdx) | Direct URLs to video or image creatives, hosted on your CDN. | Nothing. | +| [VAST](./ad-workflows/vast.mdx) | A VAST tag URL from your ad server. | On Web, Google's client-side IMA SDK (`ima3.js`) on the page. Nothing on Android, iOS, React Native. | +| [Google Pod Serving](./ad-workflows/google-pod-serving.mdx) | An ad pod decisioned by Google Ad Manager. | On Web, Google's IMA DAI SDK (`ima3_dai.js`) on the page. Nothing on Android, iOS, React Native. | + +The platform guides cover the integration that every workflow shares: installing the SDK, wrapping your player, and starting a session. The workflow pages describe how to set up breaks for each workflow, which layouts it supports, and how to troubleshoot it. + ## Configuration Configuration is split into two levels: @@ -24,32 +36,36 @@ 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. +Neither level holds ad server URLs or accounts. What to play, and where to fetch it from, comes from the channel's Break Manifest — including the Google Ad Manager settings for [Google Pod Serving](./ad-workflows/google-pod-serving.mdx). + ### 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. | +| 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` | Optional. Google Pod Serving starts automatically when the Break Manifest carries a Google configuration; set `enabled` to `false` to keep Google out of a session. See [Google Pod Serving](./ad-workflows/google-pod-serving.mdx#turn-google-off-for-a-session). | +| `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). | +| Property | Description | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `manifestUrl` | The channel's Break Manifest URL. **Required.** See [Retrieving the required values](#retrieving-the-required-values). | +| `assetParameters` | Session-level ad targeting parameters for VAST and Google Pod Serving breaks: appended to VAST tag URLs, or sent to Google as `adTagParameters`. Static assets do not use them. See [Ad targeting parameters](../../how-to-guides/ad-tag-parameters.mdx). | ## Retrieving the required values +The Break Manifest URL is the only value your app needs: + - **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 +You do not configure ad server values in the app. VAST tag URLs are set on the breaks, and for Google Pod Serving the network code and the custom asset key are configured on the channel and delivered to the SDK through the Break Manifest. + +## Next steps import DocCardList from '@theme/DocCardList'; @@ -57,9 +73,9 @@ 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. | +| 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. | +| [Ad targeting parameters](../../how-to-guides/ad-tag-parameters.mdx) | Passing targeting parameters to VAST tags and Google. | diff --git a/ads/player-integration/optiview-ads-sdk/ios.mdx b/ads/player-integration/optiview-ads-sdk/ios.mdx index 6cbdcd2f4a44..fb7c8826017b 100644 --- a/ads/player-integration/optiview-ads-sdk/ios.mdx +++ b/ads/player-integration/optiview-ads-sdk/ios.mdx @@ -10,7 +10,7 @@ On iOS and tvOS, the OptiView Ads SDK is a native Swift library that works with ## 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. +2. Check which [ad workflows](./index.mdx#ad-workflows) your breaks use. On iOS and tvOS, static assets, VAST, and Google Pod Serving all work with the installation below; nothing extra is needed. 3. Install the SDK together with the adapter for your player (see [Installation](#installation) and the player sections below). ## Installation @@ -30,11 +30,11 @@ target 'MyApp' do end ``` -The runtime pod also brings in the Google IMA SDK. +The runtime pod also brings in the Google IMA SDK, which the SDK uses to play [VAST](./ad-workflows/vast.mdx) and [Google Pod Serving](./ad-workflows/google-pod-serving.mdx) breaks. ### Swift Package Manager -Add the package from [https://github.com/Dolby-OptiView/optiview-ads-sdk-spm](https://github.com/Dolby-OptiView/optiview-ads-sdk-spm) and link the `OptiViewAdsRuntime` product. Because the frameworks are binary targets, also add the Google IMA package for each platform you build for: +Add the package from [https://github.com/Dolby-OptiView/optiview-ads-sdk-spm](https://github.com/Dolby-OptiView/optiview-ads-sdk-spm) and link the `OptiViewAdsRuntime` product. Because the frameworks are binary targets, also add the Google IMA package for each platform you build for. The runtime always links against Google IMA, so the package is required even if your breaks only use static assets: ```swift dependencies: [ diff --git a/ads/player-integration/optiview-ads-sdk/react-native.mdx b/ads/player-integration/optiview-ads-sdk/react-native.mdx index c2cb9d5ea433..ca2682bd6b68 100644 --- a/ads/player-integration/optiview-ads-sdk/react-native.mdx +++ b/ads/player-integration/optiview-ads-sdk/react-native.mdx @@ -10,7 +10,7 @@ On React Native, the OptiView Ads SDK bridges the native Android and iOS SDKs be ## 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. +2. Check which [ad workflows](./index.mdx#ad-workflows) your breaks use. On React Native, static assets, VAST, and Google Pod Serving all work with the installation below; nothing extra is needed. 3. Install the SDK and make its native dependencies resolvable for your platforms (see [Installation](#installation)). ## Installation @@ -57,7 +57,7 @@ import { createOptiViewAds } from '@dolby-optiview/ads-sdk-react-native'; const onPlayerReady = async (player) => { player.source = { sources: [{ src: CONTENT_URL, type: 'application/x-mpegurl' }] }; - const ads = createOptiViewAds(player, { gam: { networkCode: 'NETWORK-CODE' } }); + const ads = createOptiViewAds(player, {}); await ads.startSession({ manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/ORG-ID/channels/CHANNEL-ID', }); @@ -92,7 +92,7 @@ const { player, onVideoEvent } = useReactVideoHandle(); useEffect(() => { if (!player) return; - const ads = createOptiViewAds(player, { gam: { networkCode: 'NETWORK-CODE' } }); + const ads = createOptiViewAds(player, {}); void ads.startSession({ manifestUrl: MANIFEST_URL }); return () => void ads.destroy(); }, [player]); diff --git a/ads/player-integration/optiview-ads-sdk/web.mdx b/ads/player-integration/optiview-ads-sdk/web.mdx index ed81358afe84..43c01a08acb1 100644 --- a/ads/player-integration/optiview-ads-sdk/web.mdx +++ b/ads/player-integration/optiview-ads-sdk/web.mdx @@ -10,7 +10,7 @@ On Web, the OptiView Ads SDK works with any HLS-capable player through a player ## 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. +2. Check which [ad workflows](./index.mdx#ad-workflows) your breaks use. Static assets need nothing extra; [VAST](./ad-workflows/vast.mdx) and [Google Pod Serving](./ad-workflows/google-pod-serving.mdx) each need a Google IMA script on the page. 3. Install the SDK together with the adapter for your player (see the player sections below). ## Integration @@ -24,7 +24,6 @@ import { THEOplayerAdapter } from '@dolby-optiview/ads-sdk-adapter-theoplayer'; const sdk = new OptiViewAds({ player: new THEOplayerAdapter(player, container), container: document.getElementById('container'), - gam: { networkCode: 'NETWORK-CODE' }, }); await sdk.startSession({ @@ -34,6 +33,8 @@ await sdk.startSession({ 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. +This integration is the same for every ad workflow. If your breaks use VAST or Google Pod Serving, also load the Google IMA script that the [VAST](./ad-workflows/vast.mdx#what-your-app-needs) or [Google Pod Serving](./ad-workflows/google-pod-serving.mdx#what-your-app-needs) page lists. + All configuration options, session settings, and ad events are documented in the [Web API reference](pathname:///ads/v2/api-reference/web/), starting from the [`OptiViewAds`](pathname:///ads/v2/api-reference/web/classes/OptiViewAds.html) class. ## Supported players diff --git a/sidebarsAds.ts b/sidebarsAds.ts index 90892d2e98f7..9b36668ea928 100644 --- a/sidebarsAds.ts +++ b/sidebarsAds.ts @@ -35,6 +35,16 @@ const sidebars: SidebarsConfig = { 'player-integration/optiview-ads-sdk/android', 'player-integration/optiview-ads-sdk/ios', 'player-integration/optiview-ads-sdk/react-native', + { + type: 'category', + label: 'Ad workflows', + description: 'Static assets, VAST, and Google Pod Serving.', + items: [ + 'player-integration/optiview-ads-sdk/ad-workflows/static-assets', + 'player-integration/optiview-ads-sdk/ad-workflows/vast', + 'player-integration/optiview-ads-sdk/ad-workflows/google-pod-serving', + ], + }, ], }, {