Ads: document ad workflows by use case (live, VOD) and ad source (static, VAST, Google Ad Manager)

ads/concepts/breaks.mdx

@@ -25,6 +25,7 @@ The [timebase of the channel](./channels.mdx#timebase) defines how a break is sc
 
 - **`wallclock`** — the break's `start` is a UTC ISO 8601 timestamp (for example `"2026-07-16T12:15:00.000Z"`). Players match it against the wallclock timeline carried by the stream. `start` is optional on wallclock channels: omitting it creates a [cued break](#cued-breaks).
 - **`pts`** — the break's `start` is a non-negative number: a presentation timestamp on the encoder's timeline. `start` is required on PTS channels.
+- **`mediatime`** — the break's `start` is a non-negative number of seconds from the start of the asset (for example `600`). `start` is required on `mediatime` channels, which are always [VOD](../workflows/vod/index.mdx) channels.
 
 `duration` is always required and is expressed in seconds. It is the **maximum** duration of the break.
 
@@ -396,6 +397,8 @@ A `static` asset is a media resource the player retrieves directly — a video o
 }
 ```
 
+See [Static assets](../workflows/live/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`:
@@ -409,6 +412,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](../workflows/live/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:

ads/concepts/channels.mdx

@@ -5,7 +5,7 @@ sidebar_label: Channels
 
 # Channels
 
-A channel represents one live stream in OptiView Ads. It is the place where you decide how ads behave for that stream: how break start times are interpreted, which breaks are announced to players and when, and whether ad markers in the stream are detected automatically.
+A channel represents one live stream or one video-on-demand (VOD) asset in OptiView Ads. It is the place where you decide how ads behave for that content: how break start times are interpreted, which breaks are announced to players and when, and whether ad markers in the stream are detected automatically.
 
 Everything else in OptiView Ads hangs off a channel. Origins, marker rules, breaks, events, templates, and integrations are all created for — or looked up through — a channel.
 
@@ -30,14 +30,22 @@ Every channel has a customer-facing `id`. We recommend using a UUID as the chann
 
 These channel settings determine how break start times are interpreted and how breaks are delivered to players through the [Break Manifest](./break-manifest.mdx).
 
+### Stream type
+
+The `streamType` determines the use case of the channel:
+
+- **`live`** (default) — a live stream. Players poll the Break Manifest continuously and receive breaks as they become relevant. See [Live](../workflows/live/index.mdx).
+- **`vod`** — an on-demand asset. The Break Manifest lists all breaks upfront and players fetch it once. VOD channels have no events. See [VOD](../workflows/vod/index.mdx).
+
 ### Timebase
 
 The `timebase` determines which timeline break start times are expressed on:
 
-- **`wallclock`** — breaks are scheduled with a UTC timestamp that is matched against the wallclock timeline carried by the stream itself. Use this when the stream carries wallclock timing: in HLS this comes from `EXT-X-PROGRAM-DATE-TIME` tags, in DASH from the MPD's `availabilityStartTime` combined with the segment timeline (optionally synchronized through a `UTCTiming` element).
-- **`pts`** — breaks are scheduled with a presentation timestamp (PTS) on the encoder's timeline. The player retrieves the PTS value from the media segments to know where it is on that timeline. Use this when your workflow schedules breaks against encoder PTS values rather than wallclock time.
+- **`wallclock`** — breaks are scheduled with a UTC timestamp that is matched against the wallclock timeline carried by the stream itself. Use this when the stream carries wallclock timing: in HLS this comes from `EXT-X-PROGRAM-DATE-TIME` tags, in DASH from the MPD's `availabilityStartTime` combined with the segment timeline (optionally synchronized through a `UTCTiming` element). Available for live and VOD channels.
+- **`pts`** — breaks are scheduled with a presentation timestamp (PTS) on the encoder's timeline. The player retrieves the PTS value from the media segments to know where it is on that timeline. Use this when your workflow schedules breaks against encoder PTS values rather than wallclock time. Live channels only.
+- **`mediatime`** — breaks are scheduled with a position in the asset, in seconds from its start (for example `600` for 10 minutes in). VOD channels only.
 
-Choose the timebase when creating the channel; all breaks on the channel use the same timebase.
+Choose the stream type and the timebase when creating the channel; both are fixed afterwards, and all breaks on the channel use the same timebase.
 
 ### DVR window
 

ads/getting-started/index.mdx

@@ -10,7 +10,7 @@ import RebrandingNotice from '../callouts/_rebranding_notice.md';
 
 <RebrandingNotice />
 
-OptiView Ads monetizes your live stream with Server-Guided Ad Insertion (SGAI): you schedule ad breaks on a channel, and the player renders them on top of your content — without touching your media stream. This guide takes you from an empty organization to seeing your first ad break play out on your device.
+OptiView Ads monetizes your live stream with Server-Guided Ad Insertion (SGAI): you schedule ad breaks on a channel, and the player renders them on top of your content — without touching your media stream. This guide takes you from an empty organization to seeing your first ad break play out on your device. It uses a live channel; to monetize on-demand assets, the same steps apply to a [VOD channel](/ads/workflows/vod/) with breaks at positions in the asset.
 
 The examples use the US region (`https://us.ads.optiview.dolby.com` and `https://us.markers.optiview.dolby.com`). For the EU region, replace `us.` with `eu.`.
 
@@ -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/workflows/): static assets from your CDN, VAST tags from your ad server, and Google Ad Manager — on live and VOD channels. Static assets need nothing more; for VAST or Google Ad Manager 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/workflows/live/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/<channel-id>/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 `<start-time>` with an ISO 8601 UTC timestamp a few minutes in the future, for example `2026-01-01T12:00:00.000Z`.
+Replace `<start-time>` 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/workflows/live/vast) asset or [Google Ad Manager](/ads/workflows/live/google-ad-manager).
 
 Once you schedule breaks regularly, [templates](/ads/concepts/templates) let you preconfigure the break payload so scheduling becomes a one-liner.
 
@@ -121,7 +125,7 @@ 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`, 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.
@@ -131,6 +135,7 @@ If the break does not play, verify that the Break Manifest URL from step 2 retur
 | Resource                                                      | Description                                                       |
 | ------------------------------------------------------------- | ----------------------------------------------------------------- |
 | [Player integration](/ads/player-integration/)                | The full integration guides for the SDK and the OptiView Player.  |
+| [Ad workflows](/ads/workflows/)                               | Static assets, VAST, and Google Ad Manager 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.     |

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](../workflows/index.mdx):
 
-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](../workflows/live/vast.mdx):** the SDK appends them to the VAST tag URL as URL-encoded query parameters.
+- **[Google Ad Manager](../workflows/live/google-ad-manager.mdx):** they are sent to Google as ad tag parameters (`adTagParameters`). See Google's [list of all recognized ad tag parameters](https://support.google.com/admanager/answer/10678356#expand-all).
+- **[Static assets](../workflows/live/static-assets.mdx):** the SDK appends them as query parameters to the URL of the creative it requests.
+
+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
+
+The layers are merged **per key**, from lowest to highest precedence:
 
-1. The break's `assetParameters` from the backend.
-2. The session's `assetParameters` from `startSession()`.
-3. The latest `updateAssetParameters()` call.
+1. The session's `assetParameters` from `startSession()`.
+2. The latest `updateAssetParameters()` call.
+3. The break's `assetParameters` from the backend.
 
-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.
+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,12 @@ 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 with a value from the device when it builds the ad request. For example, `"size": "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT$"` is sent as `size=1920x1080`. The SDK has built-in macros for the player size, the ad duration, and the user agent, and your app can register its own.
+
+See [Asset parameter macros](./asset-parameter-macros.mdx) for how macros work, the built-in macros, registering and updating your own, and leaving out a parameter with an empty macro.
+
 ## 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.
@@ -120,6 +145,9 @@ ads.updateAssetParameters({ cust_params: 'sport=basketball' });
 
 | Resource                                                             | Description                                     |
 | -------------------------------------------------------------------- | ----------------------------------------------- |
+| [Asset parameter macros](./asset-parameter-macros.mdx)               | Device values in parameter values.              |
+| [VAST](../workflows/live/vast.mdx)                                   | Playing VAST tags with the SDK.                 |
+| [Google Ad Manager](../workflows/live/google-ad-manager.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 vendor assets.           |
+| [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.           |