# Your ad server (VAST) on live

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 on live streams when you run your own ad server, or buy from partners that deliver their ads through VAST tags.

|                | Your ad server (VAST) on live                                      |
| -------------- | ------------------------------------------------------------------ |
| Delivery mode  | Server-guided (SGAI)                                               |
| Ad decisioning | Your ad server, per viewer, when the SDK requests the tag          |
| Break creation | Scheduled, punched, or detected from the ad markers in your stream |
| Your app needs | The OptiView Ads SDK; on Web also Google's client-side IMA SDK     |

## Before you start

* A [live channel](https://optiview.dolby.com/docs/ads/workflows/live.md#set-up-a-live-channel). The examples use the `wallclock` timebase.
* The OptiView Ads SDK in your app: [Web](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/web.md), [Android](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/android.md), [iOS](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/ios.md), or [React Native](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/react-native.md).
* A VAST tag URL from your ad server, or an advertiser's.

## What your app needs

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, although a Google Ad Manager VAST tag works too.

| 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](https://optiview.dolby.com/docs/ads/player-integration/optiview-ads-sdk/ios.md#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
<script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
```

Without it, the SDK cannot play VAST breaks: it reports `DA-VAST-IMA-SDK-MISSING` and returns to your content. If your channel also has Google Ad Manager breaks, load `ima3_dai.js` as well; the two scripts work side by side.

## Schedule a break

A VAST asset sets `type` to `vast` and `uri` to the VAST tag URL. On a `wallclock` channel, `start` is the UTC moment in your stream when the break begins:

```bash
curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels/<channel-id>/breaks' \
  -u "$ADS_API_KEY:$ADS_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'X-Org-ID: <org-id>' \
  -d '{
    "start": "2026-07-16T12:15:00.000Z",
    "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](https://optiview.dolby.com/docs/ads/concepts/breaks.md#vast-assets) and [Asset URI targeting](https://optiview.dolby.com/docs/ads/concepts/breaks.md#asset-uri-targeting) for the full asset model.

### Other ways to create the break

* **Punch it live.** Create the break without a `start`, and [punch](https://optiview.dolby.com/docs/ads/concepts/breaks.md#break-punching) it when the moment comes.
* **Detect it.** Add your stream as an [origin](https://optiview.dolby.com/docs/ads/concepts/origins.md) and configure a [marker rule](https://optiview.dolby.com/docs/ads/concepts/marker-detection.md) whose [template](https://optiview.dolby.com/docs/ads/concepts/templates.md) holds the VAST asset. Every matching ad marker in the stream becomes a break.
* **Trigger it on a player event.** Set `start` to `{ "type": "event", "event": "start" }` for a pre-roll when the viewer tunes in, `"pause"` for a pause ad, or `"end"` for a post-roll. See [Event based triggers](https://optiview.dolby.com/docs/ads/concepts/breaks.md#event-based-triggers).

## How the break plays

* The SDK receives the break through the channel's [Break Manifest](https://optiview.dolby.com/docs/ads/concepts/break-manifest.md) shortly before it starts, and requests the VAST tag on the device. Every viewer gets an individual ad decision.
* Many viewers reach a live break at the same moment, so your ad server receives a peak of requests at every break start. Make sure it is sized for your concurrent audience.
* On a channel that steers some devices to [SSAI](https://optiview.dolby.com/docs/ads/workflows.md#hybrid-ad-insertion-sgai-and-ssai), VAST breaks on the timeline are not played on those devices.

## Supported layouts

VAST describes a linear (video) ad, so VAST assets work in the [layouts](https://optiview.dolby.com/docs/ads/concepts/breaks.md#layouts) where an ad video plays:

| Layout          | VAST asset                                                                                                           |
| --------------- | -------------------------------------------------------------------------------------------------------------------- |
| Single          | Supported.                                                                                                           |
| Double box      | Supported. The VAST ad plays in the ad box, and the asset's `companion` fills the background.                        |
| L-shape ad      | Supported. The VAST ad plays in the ad window, and the asset's `companion` fills the L-shaped backdrop.              |
| L-shape content | Not supported. The SDK does not play the asset and reports `DA-VAST-UNSUPPORTED-FORMAT`. Use a static asset instead. |
| Overlay         | Not supported. The SDK does not play the asset and reports `DA-VAST-UNSUPPORTED-FORMAT`. Use a static asset instead. |

VAST assets can also be used for [pause ads](https://optiview.dolby.com/docs/ads/concepts/breaks.md#pause): 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 (SGAI) sessions 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](https://optiview.dolby.com/docs/ads/how-to-guides/ad-tag-parameters.md) 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](https://optiview.dolby.com/docs/ads/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                                                  |
| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Live](https://optiview.dolby.com/docs/ads/workflows/live.md)                                        | Live channels: timebase, break creation, and delivery modes. |
| [Breaks](https://optiview.dolby.com/docs/ads/concepts/breaks.md)                                     | Layouts, variants, controls, and the asset model.            |
| [Ad targeting parameters](https://optiview.dolby.com/docs/ads/how-to-guides/ad-tag-parameters.md)    | Passing targeting parameters to your ad server.              |
| [Static assets on live](https://optiview.dolby.com/docs/ads/workflows/live/static-assets.md)         | Play creatives from your CDN without an ad server.           |
| [Google Ad Manager on live](https://optiview.dolby.com/docs/ads/workflows/live/google-ad-manager.md) | Let Google Ad Manager fill your breaks.                      |
| [Your ad server (VAST) on VOD](https://optiview.dolby.com/docs/ads/workflows/vod/vast.md)            | The same workflow for on-demand assets.                      |