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 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. The examples use the wallclock 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 wallclock channel, start is the UTC moment in your stream when the break begins:

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 and 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 it when the moment comes.
• Detect it. Add your stream as an origin and configure a marker rule whose template 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.

How the break plays

• The SDK receives the break through the channel's Break Manifest 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, 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 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
Live	Live channels: timebase, break creation, and delivery modes.
Breaks	Layouts, variants, controls, and the asset model.
Ad targeting parameters	Passing targeting parameters to your ad server.
Static assets on live	Play creatives from your CDN without an ad server.
Google Ad Manager on live	Let Google Ad Manager fill your breaks.
Your ad server (VAST) on VOD	The same workflow for on-demand assets.