# Ad workflows

OptiView Ads is a **hybrid ad insertion platform**: the same channel and the same breaks can be delivered server-guided (SGAI) or server-side (SSAI), for live streams and for video-on-demand (VOD) assets. Your ad workflow comes down to three choices:

1. **Use case** — are you monetizing a [live stream](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live.md) or a [VOD asset](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/vod.md)?
2. **Ad source** — where do the ads come from: static assets from your CDN, your ad server through VAST tags, or Google Ad Manager?
3. **Delivery mode** — does the player insert the ads (SGAI), or are they stitched into the stream (SSAI)?

Start from your use case, [Live](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live.md) or [VOD](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/vod.md): each has a page per ad source with everything you need to set it up.

## Hybrid ad insertion: SGAI and SSAI

| Delivery mode                         | How it works                                                                                                                                                                                                                                                                                                                          | Use it for                                                                                                                                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Server-Guided Ad Insertion (SGAI)** | The OptiView Ads backend publishes the breaks in a side-loaded [Break Manifest](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/break-manifest.md). The [OptiView Ads SDK](https://docs-preview.optiview.dolby.com/pr-981/ads/player-integration/optiview-ads-sdk.md) reads it, and plays the ads on top of your content. | Web, mobile, and most connected TV apps. Required for the advanced [layouts](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/breaks.md#layouts) such as double box, L-shape, and overlays. |
| **Server-Side Ad Insertion (SSAI)**   | The ads are stitched into the media stream before it reaches the player. The player plays one continuous stream.                                                                                                                                                                                                                      | Platforms where a client-side SDK is not an option, such as older connected TV devices.                                                                                                                |

Both modes share the same model: you create a [channel](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/channels.md), schedule or detect [breaks](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/breaks.md) on it, and OptiView Ads delivers them. You do not maintain two ad setups.

A channel can **steer the delivery mode per device**: for example SGAI on web and mobile, and SSAI on a specific connected TV platform. The Break Manifest then carries the [delivery rules](#delivery-rules), and the SDK picks the mode for the device it runs on when the session starts. In SSAI mode, the SDK still plays the [event-triggered breaks](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/breaks.md#event-based-triggers) — pre-roll, pause, and post-roll — on the device, because they depend on what the individual viewer does.

SSAI is available with Google Ad Manager, through Google DAI. Static assets and VAST tags are always played server-guided.

## Delivery rules

The channel's `delivery` setting is an ordered list of rules. Each rule picks a delivery mode and, optionally, the devices it applies to:

| Field       | Required | Description                                                                                |
| ----------- | -------- | ------------------------------------------------------------------------------------------ |
| `mode`      | Yes      | `sgai` or `ssai`.                                                                          |
| `targeting` | No       | The devices the rule applies to, see [Targeting](#targeting). Omit it to make the default. |

* The SDK checks the rules in order and uses the `mode` of the **first rule that matches** the device.
* A rule without `targeting` matches every device, so put it last as the default.
* When the channel has no rules, or no rule matches, the device uses SGAI.
* A device steered to `ssai` needs an integration in effect that provides a server-side stream, currently [Google DAI](https://docs-preview.optiview.dolby.com/pr-981/ads/integrations/google/dai.md). Without one, the SDK reports an error to your app instead of falling back to SGAI.

The rules are set on the [channel](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/channels.md#delivery). An [event](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/events.md#delivery-and-ad-start-delay) can replace them for its window.

### Targeting

A rule's `targeting` matches a device when **every field it sets matches**. A field you omit matches any device. Each field holds one value: to target several device types, platforms or OS versions, add one rule per combination.

| Field        | Values                                                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `deviceType` | `console`, `desktop`, `tablet`, `mobile`, `tv`. A game console is `console`, not `tv`.                                          |
| `platform`   | The runtime the player runs on: `web`, `android`, `ios`, `tvos`, `roku`.                                                        |
| `os`         | The operating system as the device reports it, see [Operating systems](#operating-systems).                                     |
| `osVersion`  | A range of OS versions, `{ "min": "...", "max": "..." }`, used together with `os`. See [OS version ranges](#os-version-ranges). |

The device type is independent of the platform. A browser on a smart TV is `platform: "web"` with `deviceType: "tv"`, an Android TV app is `platform: "android"` with `deviceType: "tv"`, and a browser on an Xbox is `platform: "web"` with `deviceType: "console"`.

### Operating systems

| `os`       | Device                                                                  |
| ---------- | ----------------------------------------------------------------------- |
| `android`  | Android, including Android TV, Google TV and Fire TV                    |
| `chromeos` | A browser on a Chromebook. An Android app on a Chromebook is `android`. |
| `ios`      | iOS                                                                     |
| `ipados`   | An iPad                                                                 |
| `linux`    | Linux                                                                   |
| `macos`    | macOS                                                                   |
| `rokuos`   | A Roku device                                                           |
| `tizen`    | A Samsung smart TV                                                      |
| `tvos`     | tvOS                                                                    |
| `vizio`    | A Vizio smart TV                                                        |
| `webos`    | An LG smart TV                                                          |
| `windows`  | Windows                                                                 |
| `xbox`     | An Xbox console                                                         |

On the web, the SDK takes the OS from the browser's User-Agent:

* iPad Safari requests the desktop site by default and then identifies as a Mac. Such an iPad is `os: "macos"` with `deviceType: "desktop"`, so a rule targeting `ipados` or `tablet` does not reach it.
* Samsung, LG and Vizio TVs and Xbox consoles are reported as `tizen`, `webos`, `vizio` and `xbox`, even when their User-Agent also names Linux, Windows or Android. A rule targeting `linux`, `windows` or `android` does not match them.

### OS version ranges

`osVersion` limits a rule to a range of versions of its `os`:

* Set `min`, `max`, or both. Both bounds are inclusive, and `min` must not be above `max`.
* Versions are dot-separated integers, such as `5` or `6.5`.
* A bound compares only the parts it specifies, part by part as integers. Extra parts of the device version are ignored, and a part the device version lacks counts as `0`: `max: "3"` matches `3.2.1`, `min: "6.5"` matches `6.5.0` but not `6.4.9`.
* `vizio` and `xbox` report no OS version, so a rule for them cannot set `osVersion`.
* A device whose OS version is unknown does not match a rule with `osVersion`.

### Example: SSAI for older iOS versions

This channel `delivery` sends devices on iOS up to iOS 15 (any 15.x) to SSAI, and every other device to SGAI:

```json
{
  "delivery": [
    {
      "mode": "ssai",
      "targeting": {
        "os": "ios",
        "osVersion": { "max": "15" }
      }
    },
    { "mode": "sgai" }
  ]
}
```

The first rule matches a device on iOS 14.8 or 15.7, but not on iOS 16. An iPad reports `ipados`, so it is not covered by this rule. All other devices fall through to the default rule.

## Live and VOD

Live and VOD are different use cases, and a channel is created for one of them. The difference is mainly in how breaks are placed on the timeline and how players receive them:

|                     | [Live](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live.md)                                                                                                    | [VOD](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/vod.md)                                     |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Channel             | `streamType: "live"` (the default)                                                                                                                                              | `streamType: "vod"`                                                                                            |
| Break start         | A moment on the live timeline: a UTC timestamp (`wallclock`)                                                                                                                    | A position in the asset: seconds from the start (`mediatime`), or a UTC timestamp (`wallclock`)                |
| How breaks are made | Scheduled ahead or on the spot, [punched](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/breaks.md#break-punching) live, or detected from ad markers in the stream | Scheduled upfront, for example as pre-roll, mid-rolls, and post-roll, or detected from ad markers in the asset |
| Break Manifest      | Polled continuously; breaks appear as they become relevant                                                                                                                      | Fetched once at the start of playback; it lists all breaks                                                     |
| Events              | [Events](https://docs-preview.optiview.dolby.com/pr-981/ads/concepts/events.md) group the breaks of a live event                                                                | Not used                                                                                                       |

## Supported workflows

Every ad source works for both live and VOD. One channel, and even one break, can mix ad sources.

| Ad source             | What the break carries                                | Delivery mode | What your app needs                                                        |
| --------------------- | ----------------------------------------------------- | ------------- | -------------------------------------------------------------------------- |
| Static assets         | Direct URLs to video or image creatives on your CDN.  | SGAI          | Nothing beyond the SDK integration.                                        |
| Your ad server (VAST) | A VAST tag URL on your ad server, or an advertiser's. | SGAI          | On Web, Google's client-side IMA SDK (`ima3.js`).                          |
| Google Ad Manager     | An ad pod decisioned by Google Ad Manager 360.        | SGAI + SSAI   | On Web, Google's IMA DAI SDK (`ima3_dai.js`). Google Ad Manager 360 setup. |

### Which ad source should I use?

* **Static assets** when you know which creative to show: direct-sold campaigns, sponsorships, promos, branded overlays. No ad server is involved.
* **Your ad server (VAST)** when your own ad server, or a partner's, decides which ad plays. Any VAST-compliant ad server works, Google Ad Manager tags included.
* **Google Ad Manager** when you sell your inventory through Google Ad Manager 360 and want Google to fill complete ad pods, or need server-side insertion through Google DAI.

## Next steps

## [🗃Live](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live.md)

[Monetize live streams and live events.](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/live.md)

## [🗃VOD](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/vod.md)

[Monetize on-demand assets.](https://docs-preview.optiview.dolby.com/pr-981/ads/workflows/vod.md)
