From 7b15202c93461623912cfe95ce15ae469a3578c5 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:27:10 +0000 Subject: [PATCH 1/7] ADS-111 rewrite Ads getting started Co-Authored-By: maarten.rimaux --- ads/getting-started/index.mdx | 139 ++++++++++- ads/getting-started/signaling-service.mdx | 263 --------------------- ads/index.mdx | 14 +- ads/static/ads/img/how_ads_works-dark.svg | 261 +++++--------------- ads/static/ads/img/how_ads_works-light.svg | 261 +++++--------------- redirectsAds.json | 2 +- 6 files changed, 273 insertions(+), 667 deletions(-) delete mode 100644 ads/getting-started/signaling-service.mdx diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index c5d1d0397e7b..776a25107b16 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -9,8 +9,145 @@ import RebrandingNotice from '../callouts/_rebranding_notice.md'; -These guides provide the steps required to get started with OptiView Ads. They cover the deployment and API integration of the Signaling Service into your existing workflow, as well as the integration of OptiView Ads into your application. +This guide walks through the end-to-end path to monetize a live stream with Server-Guided Ad Insertion (SGAI): create a channel, attach and enable an origin, define a reusable break template, schedule a break, and play it in OptiView Player. Every step is available in the OptiView Unified Dashboard and through the REST API. + +## Prerequisites + +Before you begin, you need: + +- An OptiView organization, identified by the `X-Org-ID` header. +- An API key and secret for HTTP Basic authentication. +- Your OptiView Ads base URL. The examples use `https://ads.example.com`. +- An OptiView Player license enabled for OptiView Ads. + +Set the credentials used by the examples in your shell: + +```bash +export ADS_API_KEY='your-api-key' +export ADS_API_SECRET='your-api-secret' +``` + +## 1. Create an Ads channel + +Dashboard: **Ads → Channels → New**. + +Create a channel for the live stream. The channel's timebase determines how scheduled break start times are interpreted. + +```bash +curl -X POST 'https://ads.example.com/api/v1/channels' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: org_123' \ + -d '{ + "id": "sports-main", + "name": "Sports main", + "timebase": "wallclock", + "dvrWindowMs": 300000, + "liveOffsetMs": 0, + "pollingIdleSeconds": 10, + "pollingActiveSeconds": 1, + "customAssetKey": "sports-main-custom-asset" + }' +``` + +See the [Channels concept](/ads/concepts/channels) for the channel model and the complete field reference. + +## 2. Add and enable an origin + +Dashboard: open the channel → **Overview → Origins** (add, then enable). + +Add the manifest origin with detection disabled initially, then enable it with the returned origin ID: + +```bash +curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/origins' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: org_123' \ + -d '{ + "id": "origin-primary", + "name": "Primary HLS origin", + "type": "HLS", + "url": "https://origin.example.com/live/sports-main/master.m3u8", + "enabled": false, + "priority": 0 + }' +``` + +```bash +curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/origins/origin-primary/enable' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'X-Org-ID: org_123' +``` + +See [Add an origin to a channel](/ads/concepts/channels#add-an-origin-to-a-channel) and [Marker detection lifecycle](/ads/concepts/channels#marker-detection-lifecycle). + +## 3. Define a break template + +Dashboard: **Ads → Templates → New**. + +Templates are reusable break definitions. This minimal template plays a single 30-second VAST asset: + +```bash +curl -X POST 'https://ads.example.com/api/v1/templates' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: org_123' \ + -d '{ + "id": "fullscreen-vast", + "name": "Full-screen VAST", + "duration": 30, + "variant": { + "format": "single", + "assets": [ + { + "id": "asset-1", + "type": "vast", + "mediaType": "video", + "uri": "https://ads.example.com/vast.xml" + } + ] + } + }' +``` + +The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See the [Ads API reference](/ads/api/signaling/theoads-api) for the complete template fields. + +## 4. Schedule a break + +Dashboard: open the channel → **Breaks → Schedule now**. + +Schedule a break from the template. For a `wallclock` channel, `start` is an ISO 8601 datetime; for a `pts` channel, it can be a numeric PTS value. + +```bash +export BREAK_START="$(date -u -d '+5 minutes' '+%Y-%m-%dT%H:%M:%S.000Z')" + +curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/breaks' \ + -u "$ADS_API_KEY:$ADS_API_SECRET" \ + -H 'Content-Type: application/json' \ + -H 'X-Org-ID: org_123' \ + -d "{ + \"templateId\": \"fullscreen-vast\", + \"start\": \"$BREAK_START\", + \"duration\": 30 + }" +``` + +The response includes a status such as `PREPARING`, `CUED`, `READY`, `SIGNALED`, or `ERROR`. You can also use the `/breaks/{breakId}/punch` endpoint to schedule a `CUED` break, defaulting to now. See [Scheduling breaks](/ads/how-to-guides/scheduling-breaks). + +## 5. Play via OptiView Player + +Point OptiView Player at the channel's Break Manifest. The player polls this endpoint to discover active breaks and renders the configured ad experience. The Break Manifest is a public polling endpoint that identifies the organization and channel in the path, so it needs no authentication headers: + +```bash +curl 'https://ads.example.com/manifest/v1/org_123/channels/sports-main' +``` + +Continue with the platform guides for [Web](./web), [Android](./android), [iOS](./ios), [React Native](./react-native), or [Chromecast CAF](./chromecast). import DocCardList from '@theme/DocCardList'; + +## Integrate a player + +Choose an integration path in the [Player integration](/ads/player-integration/) section. The recommended OptiView Player guides cover Web, Android, iOS, Chromecast CAF, and React Native. You can also integrate an open-source or native player directly against the Break Manifest and SSAI cue contracts. diff --git a/ads/getting-started/signaling-service.mdx b/ads/getting-started/signaling-service.mdx deleted file mode 100644 index af904930bb28..000000000000 --- a/ads/getting-started/signaling-service.mdx +++ /dev/null @@ -1,263 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Signaling service -sidebar_custom_props: { 'icon': '🛜' } ---- - -# Signaling service - -import ThemedImage from '@theme/ThemedImage'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -The Signaling Service is provided as a service and can be integrated into any existing content management workflow through its APIs, enabling seamless adoption without significant changes to your current setup. - -Developed and provided by Dolby OptiView, this service operates on your infrastructure, integrated between your CDN and media origin. It performs manifest manipulation to insert ad breaks and additional metadata for the player. Additionally, it ensures scalability of the end-to-end system through early ad break notifications to ad decisioning servers. - - - -## Infrastructure integration - -The service is deployed and operated by Dolby OptiView within the customer’s infrastructure. This setup ensures smooth integration into the existing video workflow with minimal disruption. During onboarding, Dolby OptiView provides the specific infrastructure and network requirements. Once set up, Dolby OptiView bootstraps the service, after which the customer can manage their streams and monitor the service through the REST API. - -In collaboration with the customer and Dolby OptiView's solutions team, the integration of the service into the existing video workflow is designed. Deploying the Signaling Service between the CDN and Origin ensures that regionalization, security, and localization features remain unaffected. - -> To ensure high availability, we recommend maintaining the original origin stream on a CDN as a backup, while the Signaling Service provides redundancy and failover capabilities to further enhance reliability. - -## Monetized streams - -After deployment of the Signaling Service has been completed, the next step is the creation of monetized streams. A monetized stream represents an instance of a origin stream that is processed by the Signaling Service to enable OptiView Ads for this origin stream. Created via the locally deployed REST API, it exposes a standardized HTTPS (or HTTP) endpoint for the CDN to fetch the augmented manifest. This setup ensures seamless ad insertion without needing CDN reconfiguration, even if the monetized stream is stopped and recreated. - -The monetized stream holds the following information: - -- `streamId`: Unique identifier for the monetized stream within the environment. -- `name`: Self defined descriptive name for the monetized stream. -- `description`: Optional descriptive information for the monetized stream. -- `labels`: Array of self defined labels (string). -- `layout`: Default experience layout, see [ad experience layout](/ads/how-to-guides/override-layout/). -- `origin`: Your media origin host from where the origin manifests are loaded. -- `segmentOrigin`: Your publicly available segments origin host from where the stream's video and audio segments are hosted. In most cases this is identical to the `origin` parameter. -- `assetKey`: Optional Google DAI Asset-Key linked to this stream, see [Google DAI](https://support.google.com/admanager/topic/7062524?hl=en). -- `networkCode`: Optional Google DAI Network-Code, see [Google DAI](https://support.google.com/admanager/topic/7062524?hl=en). -- `assetURI`: Optional default custom asset URI which is to be used during ad breaks. If not set it will request an ad break through Google Pod Serving using the `assetKey` and `networkCode` parameters. -- `backdropURI`: Optional URI containing the default backdrop to be used during the Double Box or L-shape ads. -- `backdropURIGamProperties`: Optional property with configuration values for a dynamic backdrop loaded via GAM to be used during the Double Box or L-shape ads. This property has priority over `backdropURI`. -- `streamType`: Optional property to specify this stream's type to be either 'LIVE' (the default) or 'VOD'. Note: this is only relevant for scheduling overlays for now and mostly takes care of expiry of scheduled ad breaks for 'LIVE'. - -```json -{ - "streamId": "optiview-ads-demo", - "name": "OptiView Ads Demo", - "description": "SGAI OptiView Ads Demo", - "labels": [], - "layout": "DOUBLE", - "origin": "https://domain.com", - "segmentOrigin": "https://segment-domain.com", - "assetKey": "google-sgai-demo", - "networkCode": "12345", - "assetURI": "https://asset.m3u8", - "backdropURI": "https://backdrop.svg" -} -``` - -### Creating a new monetized stream - -The following API endpoint creates a bare minimal new monetized stream with GAM360 Pod serving for the ad breaks using the 'SINGLE' layout: - -```bash -curl -L 'https:///ads-client/api/v1/monetized-streams' \ - -H 'Content-Type: application/json' \ - -H 'Accept: application/json' \ - -d '{ - "streamId": "string", - "name": "string", - "layout": "SINGLE", - "origin": "string", - "segmentOrigin": "string", - "assetKey": "string", - "networkCode": "string", - }' -``` - -Alternatively, you can use the assetURI variant when GAM360 Pod serving is not required: - -```bash -curl -L 'https:///ads-client/api/v1/monetized-streams' \ - -H 'Content-Type: application/json' \ - -H 'Accept: application/json' \ - -d '{ - "streamId": "string", - "name": "string", - "layout": "SINGLE", - "origin": "string", - "segmentOrigin": "string", - "assetURI": "string" - }' -``` - -### Updating an existing monetized stream - -The following API endpoint updates the properties of an existing monetized stream based on its `streamId`: - -```bash -curl -L -X PATCH 'https:///ads-client/api/v1/monetized-streams/:streamId' \ - -H 'Content-Type: application/json' \ - -H 'Accept: application/json' \ - -d '{ - "streamId": "string", - "name": "string", - "description": "string", - "labels": [ - "string" - ], - "origin": "string", - "segmentOrigin": "string", - "assetKey": "string", - "networkCode": "string", - "assetURI": "string" - }' -``` - -### Deleting an existing monetized stream - -The following API endpoint deletes an existing monetized stream based on its `streamId`. - -```bash -curl -L -X DELETE 'https:///ads-client/api/v1/monetized-streams/:streamId' \ - -H 'Accept: application/json' -``` - -### Retrieving all monetized streams - -The following API endpoint returns all existing monetized streams in the deployed environment. - -```bash -curl -X GET 'https:///ads-client/api/v1/monetized-streams' \ - -H 'accept: application/json' -``` - -The response is an array of the existing monetized stream resources. - -```json -[ - { - "id": "optiview-ads-demo", - "payload": { - "streamId": "optiview-ads-demo", - "name": "OptiView Ads Demo", - "description": "SGAI OptiView Ads Demo", - "labels": [], - "layout": "DOUBLE", - "origin": "https://domain.com", - "segmentOrigin": "https://segment-domain.com", - "assetKey": "google-sgai-demo", - "networkCode": "12345" - }, - "state": "created", - "type": "monetized-stream" - } -] -``` - -### Retrieving an individual monetized stream - -The following API endpoint returns an existing monetized stream based on its identifier (`streamId`). - -```bash -curl -L 'https:///ads-client/api/v1/monetized-streams/:streamId' \ - -H 'Accept: application/json' -``` - -The response is the monetized stream resource. - -```json -{ - "id": "optiview-ads-demo", - "payload": { - "streamId": "optiview-ads-demo", - "name": "OptiView Ads Demo", - "description": "SGAI OptiView Ads Demo", - "labels": [], - "layout": "DOUBLE", - "origin": "https://domain.com", - "segmentOrigin": "https://segment-domain.com", - "assetKey": "google-sgai-demo", - "networkCode": "12345" - }, - "state": "created", - "type": "monetized-stream" -} -``` - -Please refer to the [API reference](/ads/api/signaling/theoads-api/) for even more detailed information on the REST API. - -### Player source - -When playing an OptiView Ads source corresponding to a monetized stream, it is expected to pass a source that looks like this: - -```js -src: 'https:///signaling-service/api/v1//hls/MANIFEST-URI'; -``` - -In this URI, the `` points to the network endpoint where the OptiView Ads service is deployed, preferably a DNS entry pointing to the service IP endpoint and reachable from the CDN. -Secondly, the `` corresponds to the `streamId` for the monetized stream. -Finally, the `MANIFEST-URI` part points to the origin's manifest relative to the configured `origin` property of the monetized stream. The signaling service will concatenate the `origin` property and the MANIFEST-URI to build the origin manifest URI. -For example: - -```js -src: 'https:///signaling-service/api/v1//hls/manifest.m3u8'; -``` - -Segment URLs in the media playlists should be absolute URLs however. Segment requests don't need to pass through the Signaling Service but should be fetched directly from the CDN to the origin so as to keep the benefit of scaling via the CDN. -The `segmentOrigin` parameter should contain this publicly available endpoint to fetch the segments directly. The signaling service will concatenate the `segmentOrigin` parameter with the segment URIs in the playlists to build an absolute segment URI. - -## Scheduling ad breaks - -Once all the required monetized streams are configured, the next step is scheduling ad breaks for these monetized streams. -To accurately schedule ad breaks, the origin manifest must be valid and include date and time indications. -For HLS, this means the `EXT-X-PROGRAM-DATE-TIME` tag must be present. -Ad breaks can be signaled through either the provided REST API or by including the relevant information in the manifest itself. - -### Manifest - -When using manifest signaling, the following tags are supported: - -- `#EXT-X-DATERANGE` tag - - this is recommended because of its standardization and ability to provide more comprehensive data for improved integration. -- `#EXT-X-OATCLS-SCTE35` tag -- `#EXT-X-CUE-OUT` and `#EXT-X-CUE-OUT-CONT` tags - -Optionally, SCTE markers can be included with the tags for extra metadata. - -### REST API - -For scheduling ad breaks through the REST API, please refer to the [API definitions](/ads/api/signaling/create-monetized-stream-break/) and the example below. - -```bash -curl --location 'https:///ads-client/api/v1/monetized-streams/stream-1/break' \ ---header 'Content-Type: application/json' \ ---header 'Accept: application/json' \ ---data '{ - "id": "626cd35a-4fbf-48b8-b0cd-acc246266f88", - "startDate": "2024-09-03T08:00:00.000Z", - "duration": 60, - "source": "", - "layout": "LSHAPE_AD" -}' -``` - -For more in depth information on scheduling ad breaks we refer to our [How-to guide: Scheduling breaks](/ads/how-to-guides/scheduling-breaks/) - -For more information on this topic we refer to our [workflow integration](/ads/how-to-guides/workflow-integration/). - -# More information - -- [API reference](/ads/api/signaling/theoads-api/) -- [What is OptiView Ads?](https://optiview.dolby.com/products/server-guided-ad-insertion/) -- [The Advantages of Server-Guided Ad Insertion](https://optiview.dolby.com/solutions/personalized-advertising/) -- [Is Server-Guided Ad-Insertion (SGAI) revolutionizing streaming monetization? (blog)](https://optiview.dolby.com/resources/blog/advertising/what-is-sgai-server-guided-ad-insertion-in-streaming/) diff --git a/ads/index.mdx b/ads/index.mdx index c1e2ca8c9997..463a5f10bb47 100644 --- a/ads/index.mdx +++ b/ads/index.mdx @@ -12,7 +12,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; -OptiView Ads is an ad insertion service for LIVE content (VoD support coming soon), utilizing Server-Guided Ad Insertion (SGAI). On these pages, you'll learn how to get started with OptiView Ads, how to configure the player and integrate the signaling service APIs. +OptiView Ads is an ad insertion service for LIVE content (VoD support coming soon), utilizing Server-Guided Ad Insertion (SGAI). On these pages, you'll learn how to get started with OptiView Ads, model your live streams, schedule ad breaks, and configure OptiView Player. By logically redistributing responsibilities in the advertisement workflow, OptiView Ads: @@ -22,11 +22,7 @@ By logically redistributing responsibilities in the advertisement workflow, Opti - Maximizes workflow efficiency by reducing prefetching and over-allocation of inventory. - Enables more relevant ads through a high degree of personalization. -OptiView Ads is an advanced ad insertion service consisting of two key components: - -1. **Signaling Service**: This back-end component enriches the manifest from your existing origin with advanced ad break signaling. It integrates seamlessly with OptiView Player, the second component, to create a smooth and cohesive workflow. - -2. **OptiView Player**: The player fetches and replaces ads within the content, working closely with the Signaling Service to optimize the viewer experience across platforms. +OptiView Ads models each live stream as a **channel**. A channel monitors one or more **origins**, detects or schedules **breaks**, and can use reusable **templates** for consistent ad experiences. It generates a **Break Manifest** for OptiView Player to poll and render. -The Signaling Service is provided as a service and can be integrated into any existing content management workflow through its APIs, allowing for seamless adoption without significant changes to your current setup. - -To ensure high availability, we recommend maintaining the original origin stream on a CDN as a backup, while the Signaling Service provides redundancy and failover capabilities to further enhance reliability. - OptiView Ads is tightly integrated with [Google Ad Manager](https://developers.google.com/ad-manager/dynamic-ad-insertion 'Google DAI') for ad decisioning, transcoding, and serving, ensuring a streamlined process for ad delivery and management. +For an end-to-end walkthrough, see [Getting started with OptiView Ads](./getting-started/). For the channel model, origins, breaks, and templates, see the [Channels concept](./concepts/channels). + OptiView Ads enables innovative ad formats through OptiView Player, providing new ways to monetize content in a less intrusive manner. The out-of-the-box formats include, but are not limited to: - **Default Full Screen Ad Insertion**: Replaces the content with an advertisement. diff --git a/ads/static/ads/img/how_ads_works-dark.svg b/ads/static/ads/img/how_ads_works-dark.svg index 69cb4fc4107d..e90f3dc41020 100644 --- a/ads/static/ads/img/how_ads_works-dark.svg +++ b/ads/static/ads/img/how_ads_works-dark.svg @@ -1,197 +1,66 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + Live origin(s) + HLS / DASH / HESP + manifest + markers + + + + OptiView Ads channel + Origins & marker detection + Templates & break scheduling + Break Manifest generation + + + + Google Ad Manager + Ad decisioning + DAI pod serving + + + + Break Manifest + polled by player + + + + OptiView Player + SGAI playback + + + + Viewer + + + + + monitor + + + + early ad break notification + + + + signal + + + + poll + + + + pod request / ads + + + + playback diff --git a/ads/static/ads/img/how_ads_works-light.svg b/ads/static/ads/img/how_ads_works-light.svg index 702ccf6c1e47..3be6c6c94476 100644 --- a/ads/static/ads/img/how_ads_works-light.svg +++ b/ads/static/ads/img/how_ads_works-light.svg @@ -1,197 +1,66 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + Live origin(s) + HLS / DASH / HESP + manifest + markers + + + + OptiView Ads channel + Origins & marker detection + Templates & break scheduling + Break Manifest generation + + + + Google Ad Manager + Ad decisioning + DAI pod serving + + + + Break Manifest + polled by player + + + + OptiView Player + SGAI playback + + + + Viewer + + + + + monitor + + + + early ad break notification + + + + signal + + + + poll + + + + pod request / ads + + + + playback diff --git a/redirectsAds.json b/redirectsAds.json index e95d8548290d..de29e846d153 100644 --- a/redirectsAds.json +++ b/redirectsAds.json @@ -77,7 +77,7 @@ }, { "from": "/theoads/getting-started/signaling-service/", - "to": "/ads/getting-started/signaling-service/" + "to": "/ads/getting-started/" }, { "from": "/theoads/getting-started/web/", From 78948c991274933bdb0daf36ed251f9dbe81a2f2 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 14:59:20 +0000 Subject: [PATCH 2/7] ADS-111 fix Player integration links Co-Authored-By: maarten.rimaux --- ads/getting-started/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 776a25107b16..4413ab08b29e 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -110,7 +110,7 @@ curl -X POST 'https://ads.example.com/api/v1/templates' \ }' ``` -The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See the [Ads API reference](/ads/api/signaling/theoads-api) for the complete template fields. +The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See the [Ads API reference](/ads/api/reference/optiview-ads-api/) for the complete template fields. ## 4. Schedule a break @@ -142,7 +142,7 @@ Point OptiView Player at the channel's Break Manifest. The player polls this end curl 'https://ads.example.com/manifest/v1/org_123/channels/sports-main' ``` -Continue with the platform guides for [Web](./web), [Android](./android), [iOS](./ios), [React Native](./react-native), or [Chromecast CAF](./chromecast). +Continue with the platform guides for [Web](/ads/player-integration/optiview-player/web), [Android](/ads/player-integration/optiview-player/android), [iOS](/ads/player-integration/optiview-player/ios), [React Native](/ads/player-integration/optiview-player/react-native), or [Chromecast CAF](/ads/player-integration/optiview-player/chromecast). import DocCardList from '@theme/DocCardList'; From 800a32655ea11781d2c79c85933790446c16f8a9 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Thu, 16 Jul 2026 15:20:16 +0000 Subject: [PATCH 3/7] ADS-111 avoid future API reference link Co-Authored-By: maarten.rimaux --- ads/getting-started/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 4413ab08b29e..1f9afcadf2ce 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -110,7 +110,7 @@ curl -X POST 'https://ads.example.com/api/v1/templates' \ }' ``` -The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See the [Ads API reference](/ads/api/reference/optiview-ads-api/) for the complete template fields. +The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See [Templates](/ads/concepts/templates/) for the complete template field model. ## 4. Schedule a break From 119545a01780472a67298b84d3f71d665e1d7d6f Mon Sep 17 00:00:00 2001 From: "maarten.rimaux" Date: Mon, 17 Aug 2026 14:50:35 +0000 Subject: [PATCH 4/7] ADS-111 align player links with restructured player integration docs Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- ads/getting-started/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 1f9afcadf2ce..5c4a76543eed 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -142,7 +142,7 @@ Point OptiView Player at the channel's Break Manifest. The player polls this end curl 'https://ads.example.com/manifest/v1/org_123/channels/sports-main' ``` -Continue with the platform guides for [Web](/ads/player-integration/optiview-player/web), [Android](/ads/player-integration/optiview-player/android), [iOS](/ads/player-integration/optiview-player/ios), [React Native](/ads/player-integration/optiview-player/react-native), or [Chromecast CAF](/ads/player-integration/optiview-player/chromecast). +Continue with the platform guides for [Web](/ads/player-integration/optiview-player/web), [Android](/ads/player-integration/optiview-player/android), [iOS](/ads/player-integration/optiview-player/ios), or [React Native](/ads/player-integration/optiview-player/react-native). import DocCardList from '@theme/DocCardList'; @@ -150,4 +150,4 @@ import DocCardList from '@theme/DocCardList'; ## Integrate a player -Choose an integration path in the [Player integration](/ads/player-integration/) section. The recommended OptiView Player guides cover Web, Android, iOS, Chromecast CAF, and React Native. You can also integrate an open-source or native player directly against the Break Manifest and SSAI cue contracts. +Choose an integration path in the [Player integration](/ads/player-integration/) section. The recommended OptiView Ads SDK lets you bring your own player, while the legacy OptiView Player guides cover Web, Android, iOS, and React Native. From 21d610c28e5af3526995e6a06be927fbbf8d5896 Mon Sep 17 00:00:00 2001 From: "maarten.rimaux" Date: Mon, 17 Aug 2026 14:52:38 +0000 Subject: [PATCH 5/7] ADS-111 fix broken concept anchors on getting started Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- ads/getting-started/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 5c4a76543eed..466fe33bddd8 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -79,7 +79,7 @@ curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/origins/origin -H 'X-Org-ID: org_123' ``` -See [Add an origin to a channel](/ads/concepts/channels#add-an-origin-to-a-channel) and [Marker detection lifecycle](/ads/concepts/channels#marker-detection-lifecycle). +See [Origins](/ads/concepts/origins) and [Break Detection](/ads/concepts/marker-detection). ## 3. Define a break template From d5fb794331882590e443f73f271cdc08a0b6b684 Mon Sep 17 00:00:00 2001 From: "maarten.rimaux" Date: Mon, 17 Aug 2026 15:51:24 +0000 Subject: [PATCH 6/7] ADS-111 rewrite getting started from a customer perspective Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- ads/getting-started/index.mdx | 152 +++++++++++++++------------------- 1 file changed, 67 insertions(+), 85 deletions(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 466fe33bddd8..4a2bb0f11f7e 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -9,145 +9,127 @@ import RebrandingNotice from '../callouts/_rebranding_notice.md'; -This guide walks through the end-to-end path to monetize a live stream with Server-Guided Ad Insertion (SGAI): create a channel, attach and enable an origin, define a reusable break template, schedule a break, and play it in OptiView Player. Every step is available in the OptiView Unified Dashboard and through the REST API. +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. -## Prerequisites +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.`. -Before you begin, you need: +## Prerequisites -- An OptiView organization, identified by the `X-Org-ID` header. -- An API key and secret for HTTP Basic authentication. -- Your OptiView Ads base URL. The examples use `https://ads.example.com`. -- An OptiView Player license enabled for OptiView Ads. +Before you begin, make sure you have: -Set the credentials used by the examples in your shell: +- **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 an Ads channel +## 1. Create a channel + +A [channel](/ads/concepts/channels) 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. -Dashboard: **Ads → Channels → New**. +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. -Create a channel for the live stream. The channel's timebase determines how scheduled break start times are interpreted. +Dashboard: **Ads → Channels → New**. Or via the API: ```bash -curl -X POST 'https://ads.example.com/api/v1/channels' \ +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_123' \ -d '{ - "id": "sports-main", "name": "Sports main", - "timebase": "wallclock", - "dvrWindowMs": 300000, - "liveOffsetMs": 0, - "pollingIdleSeconds": 10, - "pollingActiveSeconds": 1, - "customAssetKey": "sports-main-custom-asset" + "timebase": "wallclock" }' ``` -See the [Channels concept](/ads/concepts/channels) for the channel model and the complete field reference. +The response contains the generated channel `id` — you will use it in the next steps. -## 2. Add and enable an origin +## 2. Retrieve the Break Manifest URL -Dashboard: open the channel → **Overview → Origins** (add, then enable). +The [Break Manifest](/ads/concepts/break-manifest) 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: -Add the manifest origin with detection disabled initially, then enable it with the returned origin ID: - -```bash -curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/origins' \ - -u "$ADS_API_KEY:$ADS_API_SECRET" \ - -H 'Content-Type: application/json' \ - -H 'X-Org-ID: org_123' \ - -d '{ - "id": "origin-primary", - "name": "Primary HLS origin", - "type": "HLS", - "url": "https://origin.example.com/live/sports-main/master.m3u8", - "enabled": false, - "priority": 0 - }' +```text +https://us.markers.optiview.dolby.com/manifest/v1/{orgId}/channels/{channelId} ``` -```bash -curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/origins/origin-primary/enable' \ - -u "$ADS_API_KEY:$ADS_API_SECRET" \ - -H 'X-Org-ID: org_123' -``` +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. -See [Origins](/ads/concepts/origins) and [Break Detection](/ads/concepts/marker-detection). +## 3. Configure the OptiView Ads SDK with your player -## 3. Define a break template +The [OptiView Ads SDK](/ads/player-integration/optiview-ads-sdk/) 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. -Dashboard: **Ads → Templates → New**. +Create the SDK with your player's adapter and start a session with the Break Manifest URL from step 2. On Web, for example: -Templates are reusable break definitions. This minimal template plays a single 30-second VAST asset: +```typescript +import { OptiViewAds } from '@dolby-optiview/ads-sdk'; +import { THEOplayerAdapter } from '@dolby-optiview/ads-adapter-theoplayer'; -```bash -curl -X POST 'https://ads.example.com/api/v1/templates' \ - -u "$ADS_API_KEY:$ADS_API_SECRET" \ - -H 'Content-Type: application/json' \ - -H 'X-Org-ID: org_123' \ - -d '{ - "id": "fullscreen-vast", - "name": "Full-screen VAST", - "duration": 30, - "variant": { - "format": "single", - "assets": [ - { - "id": "asset-1", - "type": "vast", - "mediaType": "video", - "uri": "https://ads.example.com/vast.xml" - } - ] - } - }' +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_123/channels/CHANNEL-ID', +}); ``` -The supported break formats are `single`, `double`, `lshape_ad`, `lshape_content`, and `overlay`. For Google Ad Manager pod serving, use an asset with `type: "vendor"`, `vendor: "gam"`, and `vendorParameters` such as `{ "type": "pod" }`; this uses the channel's `customAssetKey`. See [Templates](/ads/concepts/templates/) for the complete template field model. +Follow the platform guide for [Web](/ads/player-integration/optiview-ads-sdk/web), [Android](/ads/player-integration/optiview-ads-sdk/android), [iOS](/ads/player-integration/optiview-ads-sdk/ios), or [React Native](/ads/player-integration/optiview-ads-sdk/react-native). If you use the OptiView Player, the legacy [OptiView Player integration](/ads/player-integration/optiview-player/) is also available. ## 4. Schedule a break -Dashboard: open the channel → **Breaks → Schedule now**. +A [break](/ads/concepts/breaks) describes an ad opportunity: when it starts, how long it lasts, and which ad experience plays. The simplest break plays a single full-screen ad from a VAST tag. -Schedule a break from the template. For a `wallclock` channel, `start` is an ISO 8601 datetime; for a `pts` channel, it can be a numeric PTS value. +Dashboard: open the channel → **Breaks → Schedule now**. Or via the API, scheduling a 30-second break a few minutes from now: ```bash export BREAK_START="$(date -u -d '+5 minutes' '+%Y-%m-%dT%H:%M:%S.000Z')" -curl -X POST 'https://ads.example.com/api/v1/channels/sports-main/breaks' \ +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_123' \ -d "{ - \"templateId\": \"fullscreen-vast\", \"start\": \"$BREAK_START\", - \"duration\": 30 + \"duration\": 30, + \"variant\": { + \"format\": \"single\", + \"assets\": [ + { + \"type\": \"vast\", + \"mediaType\": \"video\", + \"uri\": \"https://cdn.example.com/vast.xml\" + } + ] + } }" ``` -The response includes a status such as `PREPARING`, `CUED`, `READY`, `SIGNALED`, or `ERROR`. You can also use the `/breaks/{breakId}/punch` endpoint to schedule a `CUED` break, defaulting to now. See [Scheduling breaks](/ads/how-to-guides/scheduling-breaks). - -## 5. Play via OptiView Player +Once you schedule breaks regularly, [templates](/ads/concepts/templates) let you preconfigure the break payload so scheduling becomes a one-liner. -Point OptiView Player at the channel's Break Manifest. The player polls this endpoint to discover active breaks and renders the configured ad experience. The Break Manifest is a public polling endpoint that identifies the organization and channel in the path, so it needs no authentication headers: +## 5. See the break play out -```bash -curl 'https://ads.example.com/manifest/v1/org_123/channels/sports-main' -``` +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. -Continue with the platform guides for [Web](/ads/player-integration/optiview-player/web), [Android](/ads/player-integration/optiview-player/android), [iOS](/ads/player-integration/optiview-player/ios), or [React Native](/ads/player-integration/optiview-player/react-native). +You can follow along on both sides: -import DocCardList from '@theme/DocCardList'; +- **In the dashboard or API:** the break's [lifecycle status](/ads/concepts/breaks#break-lifecycle) moves from `PREPARING` to `READY`, and 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. -## Integrate a player +## Next steps -Choose an integration path in the [Player integration](/ads/player-integration/) section. The recommended OptiView Ads SDK lets you bring your own player, while the legacy OptiView Player guides cover Web, Android, iOS, and React Native. +| Resource | Description | +| ------------------------------------------------------------- | ----------------------------------------------------------------- | +| [Player integration](/ads/player-integration/) | The full integration guides for the SDK and the OptiView Player. | +| [Breaks](/ads/concepts/breaks) | Everything a break can do: layouts, variants, controls, punching. | +| [Origins and Break Detection](/ads/concepts/marker-detection) | Turn the ad markers in your stream into breaks automatically. | +| [Google Ad Manager](/ads/integrations/google/) | Let Google Ad Manager decision the ads that fill your breaks. | From a79a7081b8fcf5065495a6167fbed36a7b669283 Mon Sep 17 00:00:00 2001 From: "maarten.rimaux" Date: Tue, 18 Aug 2026 11:08:16 +0000 Subject: [PATCH 7/7] Use and placeholders in Getting started examples Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- ads/getting-started/index.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/ads/getting-started/index.mdx b/ads/getting-started/index.mdx index 4a2bb0f11f7e..599633113c3f 100644 --- a/ads/getting-started/index.mdx +++ b/ads/getting-started/index.mdx @@ -42,7 +42,7 @@ Dashboard: **Ads → Channels → New**. Or via the API: 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_123' \ + -H 'X-Org-ID: ' \ -d '{ "name": "Sports main", "timebase": "wallclock" @@ -77,7 +77,7 @@ const sdk = new OptiViewAds({ }); await sdk.startSession({ - manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1/org_123/channels/CHANNEL-ID', + manifestUrl: 'https://us.markers.optiview.dolby.com/manifest/v1//channels/', }); ``` @@ -92,10 +92,10 @@ Dashboard: open the channel → **Breaks → Schedule now**. Or via the API, sch ```bash export BREAK_START="$(date -u -d '+5 minutes' '+%Y-%m-%dT%H:%M:%S.000Z')" -curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels/CHANNEL-ID/breaks' \ +curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels//breaks' \ -u "$ADS_API_KEY:$ADS_API_SECRET" \ -H 'Content-Type: application/json' \ - -H 'X-Org-ID: org_123' \ + -H 'X-Org-ID: ' \ -d "{ \"start\": \"$BREAK_START\", \"duration\": 30,