# Your ad server (VAST) on VOD

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 movies, episodes, replays, and clips when you run your own ad server, or buy from partners that deliver their ads through VAST tags.

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

## Before you start

* A [VOD channel](https://optiview.dolby.com/docs/ads/workflows/vod.md#set-up-a-vod-channel). The examples use the `mediatime` 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 `mediatime` channel, `start` is the position in the asset, in seconds. This mid-roll plays 10 minutes in, and viewers cannot skip it by seeking:

```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": 600,
    "duration": 30,
    "controls": { "snapback": true },
    "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.

### Pre-roll, post-roll, and pause ads

Set `start` to a player event instead of a position:

| Break     | `start`                                 |
| --------- | --------------------------------------- |
| Pre-roll  | `{ "type": "event", "event": "start" }` |
| Post-roll | `{ "type": "event", "event": "end" }`   |
| Pause ad  | `{ "type": "event", "event": "pause" }` |

See [Event based triggers](https://optiview.dolby.com/docs/ads/concepts/breaks.md#event-based-triggers).

### Detect the breaks

Instead of scheduling every break, add the asset 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 asset becomes a break at its position.

## How the break plays

* The SDK fetches the channel's [Break Manifest](https://optiview.dolby.com/docs/ads/concepts/break-manifest.md) once when the session starts, and requests each VAST tag on the device shortly before the viewer reaches its break. Every viewer gets an individual ad decision.
* Viewers reach the breaks at different moments, so the requests to your ad server are spread over time.
* The break's `duration` is the maximum: use a VAST tag that returns the right ad length, because the SDK returns to your content when the duration is reached.
* With `snapback`, a viewer who seeks past a break is taken back to the break first. See [Seeking and snapback](https://optiview.dolby.com/docs/ads/workflows/vod.md#seeking-and-snapback).

## 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                                          |
| -------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [VOD](https://optiview.dolby.com/docs/ads/workflows/vod.md)                                        | VOD channels: timebase, seeking, 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 VOD](https://optiview.dolby.com/docs/ads/workflows/vod/static-assets.md)         | Play creatives from your CDN without an ad server.   |
| [Google Ad Manager on VOD](https://optiview.dolby.com/docs/ads/workflows/vod/google-ad-manager.md) | Let Google Ad Manager fill your breaks.              |
| [Your ad server (VAST) on live](https://optiview.dolby.com/docs/ads/workflows/live/vast.md)        | The same workflow for live streams.                  |