Templates
A template is a reusable break preset for OptiView Ads. It stores a break configuration once so you can schedule consistent breaks quickly, either manually from the dashboard and API or automatically through marker rules. Break templates are managed under /templates/breaks.
Events have their own presets: event templates (/templates/events) and the integration templates they reference (/templates/integrations).
Template identity
Every template has an id that is unique within your organization. The id is optional when creating a template: if you omit it, OptiView Ads generates one for you. When you supply your own, we recommend using a UUID. For a human-readable label, use the name property instead — it is shown in the dashboard.
What a template contains
A template holds the same configuration as a break: anything you can express on a break you can preset on a template. See Break configuration for the full description of variant, resumeOffset, and controls.
A few properties differ from a break:
| Property | Difference |
|---|---|
name | A human-readable display name for the template, shown in the dashboard. |
duration | Optional on a template (it is required on a break). When set, it is the default duration for breaks scheduled from the template. |
channelIds | Channels the template is linked to, so it is surfaced when scheduling breaks on those channels. |
eventIds | Events the template is linked to. |
start | A template has no start: a template is not scheduled itself. The start is supplied when a break is scheduled from the template. |
Snapshot semantics
A template is a preset, not a live link. When a break is scheduled from a template:
- The template's configuration is copied onto the new break at creation.
- The break records the source
templateIdas provenance. - There is no synchronization afterwards. Editing or deleting the template later does not change breaks that were already created from it — they keep their copied configuration.
Scheduling a break from a template
Templates are used throughout the system to schedule breaks:
- API — create a break on a channel and reference the template with
templateId. The template configuration is snapshotted onto the break at creation. - Dashboard — use the Schedule now action on a template to create a break on the channel immediately.
- Marker rules — when an in-stream ad marker is matched against a marker rule, a break is scheduled from the template that the rule references.
An API example:
curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels/1f7f3a5a-9c2e-4a56-b1d4-3f8a2c9d6e01/breaks' \
-u "$ADS_API_KEY:$ADS_API_SECRET" \
-H 'Content-Type: application/json' \
-H 'X-Org-ID: org_123' \
-d '{
"templateId": "3b8e5f0a-7c2d-4e91-a6b3-9d4f1c8e2a70",
"start": "2026-07-16T13:00:00.000Z"
}'
templateId is the only required field. You can override the snapshotted configuration per break with the optional fields id, start, duration, variant, controls, and resumeOffset. An override replaces the template's value as a whole. For example, a variant override replaces the template's variant together with all of its assets.
Start semantics depend on the channel timebase; see Timebase-based scheduling.
Ad targeting parameters
Ad targeting parameters (assetParameters) belong to the assets of a variant. Set them in one of two places:
- On the template assets: parameters that are the same for every break scheduled from the template. They are copied onto each break with the rest of the snapshot.
- On a
variantoverride: parameters that differ per break. Pass the complete variant, including its assets and theirassetParameters, because the override replaces the template's variant.
curl -X POST 'https://us.ads.optiview.dolby.com/api/v1/channels/1f7f3a5a-9c2e-4a56-b1d4-3f8a2c9d6e01/breaks' \
-u "$ADS_API_KEY:$ADS_API_SECRET" \
-H 'Content-Type: application/json' \
-H 'X-Org-ID: org_123' \
-d '{
"templateId": "3b8e5f0a-7c2d-4e91-a6b3-9d4f1c8e2a70",
"start": "2026-07-16T13:00:00.000Z",
"variant": {
"format": "single",
"assets": [
{
"type": "vendor",
"vendor": "gam",
"mediaType": "video",
"vendorParameters": { "type": "pod" },
"assetParameters": {
"description_url": "https://www.example.com/sports/live.html",
"cust_params": "match=final"
}
}
]
}
}'
See Ad targeting parameters to learn how these parameters are combined with the parameters set in the OptiView Ads SDK.
Related resources
| Resource | Relationship |
|---|---|
| Channels | Breaks scheduled from a template are created on a channel. |
| Breaks | The result of scheduling a template: a break with the template's snapshotted content. |
| Events | An event on your channel for which you want to prepare breaks. |
| Break detection | Configure marker rules to turn ad markers in your stream into breaks. |