# Getting started with OptiView Ads

> **OptiView Rebranding**
>
> OptiView Ads is the new name for THEOads as part of the OptiView product suite. During the transition, you may still see references to THEOads. OptiView Ads and THEOads refer to the same product.

OptiView Ads monetizes your live stream with Server-Guided Ad Insertion (SGAI): you schedule ad breaks on a channel, and the player renders them on top of your content — without touching your media stream. This guide takes you from an empty organization to seeing your first ad break play out on your device. It uses a live channel; to monetize on-demand assets, the same steps apply to a [VOD channel](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/vod.md) with breaks at positions in the asset.

The examples use the US region (`https://us.ads.optiview.dolby.com` and `https://us.markers.optiview.dolby.com`). For the EU region, replace `us.` with `eu.`.

## Prerequisites

Before you begin, make sure you have:

* **An organization with the Ads product enabled.** Your organization is created in the OptiView Unified Dashboard and identifies you across all API calls (the `X-Org-ID` header). If the Ads product is not enabled for your organization yet, contact us.
* **An API key and secret.** Create an API key/secret pair in the dashboard. The pair authenticates the API calls in this guide through HTTP Basic authentication:

```bash
export ADS_API_KEY='your-api-key'
export ADS_API_SECRET='your-api-secret'
```

## 1. Create a channel

A [channel](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/channels.md) represents the live stream you want to monetize. Everything else — breaks, templates, origins — lives under a channel, so this is the first thing to create.

The only property you must choose is the **timebase**, which defines how break start times are expressed on this channel:

* `wallclock`: breaks are scheduled at real-world times (ISO 8601 datetimes). Use this when your stream carries absolute time metadata such as `EXT-X-PROGRAM-DATE-TIME`.
* `pts`: breaks are scheduled at presentation timestamps within the stream itself.

We also recommend setting a `name` so you can recognize the channel in the dashboard. All other properties have sensible defaults, and the channel `id` is generated for you as a UUID when you omit it.

Dashboard: **Ads → Channels → New**. Or via the API:

```bash
curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels' \
  -u "$ADS_API_KEY:$ADS_API_SECRET" \
  -H 'Content-Type: application/json' \
  -H 'X-Org-ID: <org-id>' \
  -d '{
    "name": "Sports main",
    "timebase": "wallclock"
  }'
```

The response contains the generated channel `id` — you will use it in the next steps.

## 2. Retrieve the Break Manifest URL

The [Break Manifest](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/break-manifest.md) is how your channel announces its breaks to the player: the player polls this endpoint and schedules the announced breaks against your stream. It is a public endpoint that identifies your organization and channel in the path, so it needs no authentication:

```text
https://us.markers.optiview.dolby.com/manifest/v1/{orgId}/channels/{channelId}
```

Fill in your organization ID and the channel ID from step 1, and keep this URL at hand — it is the one value the player integration needs.

## 3. Configure the OptiView Ads SDK with your player

The [OptiView Ads SDK](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk.md) connects your player to OptiView Ads: it polls the Break Manifest, schedules the breaks against your player's timeline, plays the ads, and reports impressions. It is player-agnostic — you keep your own player and wrap it in a small adapter.

Create the SDK with your player's adapter and start a session with the Break Manifest URL from step 2. On Web, for example:

```typescript
import { OptiViewAds } from '@dolby-optiview/ads-sdk';
import { THEOplayerAdapter } from '@dolby-optiview/ads-sdk-adapter-theoplayer';

const sdk = new OptiViewAds({
  player: new THEOplayerAdapter(player, container),
  container: document.getElementById('container'),
});

await sdk.startSession({
  manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/<org-id>/channels/<channel-id>',
});
```

Follow the platform guide for [Web](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk/web.md), [Android](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk/android.md), [iOS](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk/ios.md), or [React Native](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-ads-sdk/react-native.md). If you use the OptiView Player, the legacy [OptiView Player integration](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration/optiview-player.md) is also available.

This integration plays every [ad workflow](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows.md): static assets from your CDN, VAST tags from your ad server, and Google Ad Manager — on live and VOD channels. Static assets need nothing more; for VAST or Google Ad Manager on Web, the workflow page lists the Google IMA script to add to your page.

## 4. Schedule a break

A [break](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/breaks.md) describes an ad opportunity: when it starts, how long it lasts, and which ad experience plays. The simplest break plays a single full-screen video ad from your CDN, as a [static asset](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/static-assets.md).

Dashboard: open the channel → **Breaks → Schedule now**. Or via the API, scheduling a 30-second break a few minutes from now:

```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": "<start-time>",
    "duration": 30,
    "variant": {
      "format": "single",
      "assets": [
        {
          "type": "static",
          "mediaType": "video",
          "uri": "https://cdn.example.com/ads/spot.m3u8"
        }
      ]
    }
  }'
```

Replace `<start-time>` with an ISO 8601 UTC timestamp a few minutes in the future, for example `2026-01-01T12:00:00.000Z`, and the `uri` with the URL of an ad video on your CDN.

To let an ad server choose the ad instead, use a [VAST](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/vast.md) asset or [Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows/live/google-ad-manager.md).

Once you schedule breaks regularly, [templates](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/templates.md) let you preconfigure the break payload so scheduling becomes a one-liner.

## 5. See the break play out

Start playback of your stream on your device. Shortly before the scheduled start time, the break appears in the Break Manifest and the SDK prepares it; at the start time, the ad takes over the player.

You can follow along on both sides:

* **In the dashboard or API:** the break's [lifecycle status](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/breaks.md#break-lifecycle) is `READY`, and moves to `SIGNALED` once it is announced to players.
* **In the player:** the ad plays at the scheduled time and your content resumes afterwards.

If the break does not play, verify that the Break Manifest URL from step 2 returns the break, and that your stream carries the time metadata required by the channel's timebase.

## Next steps

| Resource                                                                                                       | Description                                                       |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [Player integration](https://docs-preview.optiview.dolby.com/pr-943/ads/player-integration.md)                 | The full integration guides for the SDK and the OptiView Player.  |
| [Ad workflows](https://docs-preview.optiview.dolby.com/pr-943/ads/workflows.md)                                | Static assets, VAST, and Google Ad Manager with the SDK.          |
| [Breaks](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/breaks.md)                                | Everything a break can do: layouts, variants, controls, punching. |
| [Origins and Break Detection](https://docs-preview.optiview.dolby.com/pr-943/ads/concepts/marker-detection.md) | Turn the ad markers in your stream into breaks automatically.     |
| [Google Ad Manager](https://docs-preview.optiview.dolby.com/pr-943/ads/integrations/google.md)                 | Let Google Ad Manager decision the ads that fill your breaks.     |