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 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. The examples use the mediatime timebase.
• The OptiView Ads SDK in your app: Web, Android, iOS, or React Native.
• 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.
React Native	Nothing extra: the native SDKs include the Google IMA SDK.

On Web, add the IMA loader to your page:

<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:

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 and 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.

Detect the breaks

Instead of scheduling every break, add the asset as an origin and configure a marker rule whose template 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 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.

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 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: 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:

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 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 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. 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	VOD channels: timebase, seeking, and delivery modes.
Breaks	Layouts, variants, controls, and the asset model.
Ad targeting parameters	Passing targeting parameters to your ad server.
Static assets on VOD	Play creatives from your CDN without an ad server.
Google Ad Manager on VOD	Let Google Ad Manager fill your breaks.
Your ad server (VAST) on live	The same workflow for live streams.