@dolby-optiview/ads-sdk 1.1.1 → 1.2.0

package/ai/reference/error-codes.md

@@ -29,13 +29,14 @@ of the public contract and are never renamed.
 | `DA-ANVATO-CUE-END-REJECTED` | break | warn | ptsSource: 'anvatoCue' — an Anvato type=cue_end was observed for the active break but its stream-clock length differs from the break duration by more than 2s, so it is ignored and the resume keeps its computed target. Emitted once per break; context: breakId, mediaTime, lengthSec, durationSec. |
 | `DA-PRELOAD-FAILED` | preload | warn | Ad preload failed; the asset will be loaded on demand at break start. |
 | `DA-PRELOAD-MODE-RESOLVED` | preload | info | The configured ad preload mode was resolved for this session; context carries both the configured and the resolved mode. |
-| `DA-PRELOAD-PATH` | preload | info | The preload path actually taken for a break's ad (parallel buffer / detached prefetch / none) and the creative container (stream vs progressive). |
+| `DA-PRELOAD-PATH` | preload | info | The preload path actually taken for a break's ad (parallel buffer / detached prefetch / first-frame warm-up on the ad player / none) and the creative container (stream vs progressive). |
 | `DA-BREAK-EARLY-RETURN` | break | info | The active break was removed from a polled manifest (early return); the break ends immediately and content resumes at break start plus the seconds already played. |
 | `DA-BREAK-WINDOW-ESCAPED` | break | warn | An active wallclock break outlived its window on the stream clock (ad stall, bogus trigger position, or a re-fired completed break); the SDK ended it and returned to content. context.overrunSec says by how much. |
 | `DA-BREAK-EVENT-UNSUPPORTED` | break | warn | A break is triggered by a spec event this SDK version does not schedule on this platform (web schedules `start`, `pause` and `end`; Android and iOS do not schedule `end` yet); the break was ignored. context.event names the event. |
 | `DA-BREAK-SUPPRESSED-OVERLAP` | break | warn | A break was suppressed because an ad was already playing. |
 | `DA-BREAK-TRANSITION` | break | info | Measured duration of a playback transition into an ad break, between two ads, between chained breaks, or back to content. |
 | `DA-AD-SURFACE-REVEALED` | break | info | The ad surface became visible: how long it was held back waiting for the ad's first frame, and whether it was revealed because that frame arrived or because the wait timed out. |
+| `DA-BREAK-CUT-LATE` | break | warn | timebase: 'wallclock', all platforms — content was cut more than 0.5s after the break's manifest start on the stream's Program Date Time, so the viewer saw the stream's own break (slate) instead of the ad until then; typically the ad's first frame was not ready at the cut and content kept playing under the cross-fade. The replaced window is unaffected: the resume anchor is the content time of the manifest start whatever the cut landed on. Context carries breakId, lateSec (cut minus start on the PDT axis), start (the manifest start), cutPdt (the PDT at the cut), cutAt (currentTime at the cut) and anchor; iOS/Android add waitedForAdMs when the cut waited for the ad surface. |
 | `DA-PREROLL-CONTENT-HELD` | break | info | Content playback was held at session start until a pending pre-roll began, so no content is shown before the ad. |
 | `DA-PREROLL-CONTENT-WAIT-TIMEOUT` | break | info | A pending pre-roll began after content readiness was not reported within the wait timeout. |
 | `DA-PREROLL-CANCELLED-CONTENT-ERROR` | break | warn | A pending pre-roll was cancelled because the content failed to load before it could begin. |
@@ -47,14 +48,21 @@ of the public contract and are never renamed.
 | `DA-CONTENT-ELEMENT-SWAPPED` | break | info | The content player replaced its <video> element; the SDK re-bound its presentation listeners to the new one. |
 | `DA-PIP-FORMAT-OVERRIDE` | break | info | The content player is in picture-in-picture, so the break's declared format was overruled and it plays as a single fullscreen ad. |
 | `DA-PIP-ADOPTION-STATE` | break | info | Native PiP reconciliation deferred or reused a layout/handoff decision. Context carries reason, active, adPlaying, applied, and asset/break IDs when available; this is not evidence that a format override occurred. |
+| `DA-PIP-HANDOFF` | break | info | The picture-in-picture handoff route chosen for the ad: 'layer-swap' (the presented AVPlayerLayer is re-pointed at the ad player) or 'borrow' (the ad plays through the content player). context: route, layers. iOS only. |
+| `DA-PIP-LAYER-SWAP` | break | debug | Read-back check after a PiP layer-swap: whether the presented layer still points at the ad player after the re-point. context: held, layers. iOS only. |
+| `DA-PIP-PRESENTED` | break | debug | Status trace of the player on the PiP-presented layer during a layer-swap: owner (ad/content/other) and time-control-status transitions, plus ad-item ends observed while presented. context: owner/status, or errored/reachedEnd/adStatus. iOS only. |
 | `DA-CHAIN-RESOLVER-ERROR` | chaining | warn | The chained-successor resolver threw; chaining was skipped for this break. |
 | `DA-GAM-NO-ASSET-KEY` | gam | warn | Retired: the GAM stream identity now comes from the manifest's vendorConfiguration. Kept declared so the code is never reused; see DA-GAM-CONFIG-MISSING. |
 | `DA-GAM-SESSION-FAILED` | gam | error | The GAM/IMA session failed to initialize; GAM breaks will not serve. |
+| `DA-GAM-START-DEFERRED` | gam | info | The SGAI IMA stream request is deferred until the configured ad start delay has been played; context includes adStartDelaySec. |
 | `DA-GAM-CONFIG-RESOLVED` | gam | info | The GAM stream identity for this session was resolved from the manifest's vendorConfiguration. |
 | `DA-GAM-CONFIG-MISSING` | gam | error | The break manifest carries no usable "gam" vendorConfiguration entry; GAM assets are skipped. |
 | `DA-GAM-POD-IDENTITY-MISMATCH` | gam | error | A GAM pod asset's vendorParameters name a different network code or custom asset key than the stream session was created with; the asset is skipped because the pod request cannot serve. |
 | `DA-GAM-POD-MID-BREAK-END` | gam | warn | IMA reported the ad break ended before the pod's last ad while pod stream remains; per-ad reporting continues until the pod ends. |
+| `DA-GAM-DUPLICATE-METADATA` | gam | info | The stream carries the same ad marker more than once at the same time (for example in both the audio and video renditions of an fMP4 stream); the duplicate was not passed to IMA, so each ad event fires once. Reported once per stream session. |
 | `DA-VENDOR-CONFIG-UNKNOWN-TYPE` | manifest | info | One or more vendorConfiguration entries declare a type this SDK version does not recognise and were ignored. |
+| `DA-EXTERNAL-VENDOR-INVALID` | manifest | warn | External vendorConfiguration entries were ignored because provider was blank or assetParameters was not an object. context: count. |
+| `DA-EXTERNAL-VENDOR-DUPLICATE` | manifest | warn | External vendorConfiguration entries repeated a provider; the first valid entry was used. context: providers. |
 | `DA-CONTENT-PLAYBACK-ERROR` | playback | error | The content player reported a playback error. |
 | `DA-CONTENT-RESUME-STALLED` | playback | warn | Content did not resume within the watchdog window after a break that paused it ended; the SDK re-issued play() once. iOS only for now. |
 | `DA-CONTENT-RECOVERY-MODE-RESOLVED` | playback | info | The resolved post-break content recovery mode for the session (recreate or none); context carries configured and resolved. |
@@ -68,7 +76,10 @@ of the public contract and are never renamed.
 | `DA-AD-START-TIMEOUT` | playback | error | The ad did not load, render a first frame or start within its start budget; reported as CMCD adec. |
 | `DA-AD-START-INTERRUPTED` | playback | warn | The ad element's play() was interrupted by a browser-initiated pause before the ad started (Chromium AbortError, seen on Samsung Tizen); the SDK re-issued play() once. context: breakId, error. |
 | `DA-AD-DURATION-PREPARED` | playback | info | The ad media for a break was prepared and its real playable duration is now known, BEFORE the first frame. context: breakId, assetId, index, total, preparedDurationSec (the loaded media's own duration — on a GAM pod, the stitched pod's length), declaredDurationSec (what the manifest said about this asset, when it said anything) and breakDurationSec (the slot the break declares). Emitted per asset, so a multi-asset break reports one per asset and the break total is their sum. The three together separate a short break caused by a short POD from one caused by a short request or a late join. |
-| `DA-DELIVERY-MODE-RESOLVED` | session | info | Delivery mode (sgai/ssai) resolved for the session at start and again on an ads-channel switch from the manifest's delivery rules (or the explicit client config). |
+| `DA-DELIVERY-MODE-RESOLVED` | session | info | Delivery mode (sgai/ssai) resolved for the session at start and again on an ads-channel switch from the manifest's delivery rules (or the explicit client config), with the detected device profile. |
+| `DA-TARGETING-VALUE-UNKNOWN` | manifest | warn | A targeting value is not recognized and the targeted entry does not match. |
+| `DA-TARGETING-FIELD-UNKNOWN` | manifest | warn | A targeting field is not recognized and the targeted entry does not match. |
+| `DA-TARGETING-INVALID` | manifest | warn | A targeting constraint is malformed or incomplete and the targeted entry does not match. |
 | `DA-DELIVERY-MODE-UNKNOWN` | session | warn | The matching delivery rule carried an unrecognized mode value; sgai is used (forward compatibility). |
 | `DA-DELIVERY-MODE-OVERRIDDEN` | session | info | The manifest's delivery rules resolved a different mode, but the explicit client config takes precedence. |
 | `DA-DELIVERY-MODE-CHANGE-IGNORED` | session | warn | An ordinary manifest poll resolves a different delivery mode; the mode pinned for the session stays in force. An ads-channel switch resolves the mode again. |
@@ -112,6 +123,9 @@ of the public contract and are never renamed.
 | `DA-RESUME-PTS-REMAP` | playback | warn | ptsSource: 'anvatoCue', iOS/tvOS and web — a stream beacon disagreed with the currentTime ↔ stream-clock mapping by more than 0.2s, so the player re-anchored currentTime (a variant switch or a buffer restart); the mapping starts over from that beacon and the resume point is mapped again. Reported during the resume run-up and after the hand-back. Context carries breakId, fromOffsetSec, toOffsetSec, deltaSec, currentTime and stage (run-up or after-hand-back). |
 | `DA-RESUME-PTS-CORRECTED` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and web — once per break at the hand-back, on a stream that carries Anvato beacons: whether the stream clock placed the live resume point, and by how much it moved it. applied=true: streamClockTarget is the resume point mapped through the beacons, correctionSec is streamClockTarget - computedTarget (the currentTime target, cue plus duration), and currentTimeShiftSec is how far the same stream instant moved in currentTime between the pause and the hand-back (negative: it now sits earlier), null when no beacon mapped the stream before the pause. Context also carries breakId, landingSource (cue_end or cue+duration), landingStreamSec, offsetSec, beacons, remaps (DA-RESUME-PTS-REMAP during the break) and cueEndTarget when a cue_end was matched. applied=false with a reason means no beacon arrived after the run-up's last seek, so the cue_end or currentTime target applied. |
 | `DA-RESUME-PTS-LANDED` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and web — where a stream-clock resume landed, measured on the stream's own clock from the beacons delivered after the hand-back: landedStreamSec is the position content resumed from (resumedAt, the seek landing or the playhead at a seek-free hand-back) converted with that mapping, and errorSec is landedStreamSec - landingStreamSec (negative: content resumed before the stream's resume point, so slate is shown). Context carries breakId, landingStreamSec, landingSource, resumedAt, sinceHandBackSec and, when measured, landedStreamSec, errorSec, offsetSec and beacons; reason when no beacon arrived within 15s. Report-only: the SDK does not correct the position from it. |
+| `DA-RESUME-PDT-MAP` | playback | info | timebase: 'wallclock', all platforms — the live resume point (the manifest start plus duration, a wallclock instant) was mapped onto currentTime through the Program Date Time the content player reports now, so a currentTime re-anchored by a seek during the break cannot move it. Reported when the run-up first reads the target and whenever the mapped target moves by 0.1s or more (remapped=true: currentTime moved against the stream). Context carries breakId, target, landingPdt (the break end, ISO-8601), pdtOffsetSec (PDT minus currentTime, seconds), currentTime, remapped, and computedTarget with deltaSec (target - computedTarget) when an anchor-based target exists. |
+| `DA-RESUME-PDT-CORRECTED` | playback | info | timebase: 'wallclock', all platforms — once per break at the hand-back of a break anchored on the Program Date Time: whether the stream clock placed the live resume point, and by how much it moved it. applied=true: pdtTarget is the break end mapped through the PDT the player reports at the hand-back, correctionSec is pdtTarget - computedTarget (the anchor plus the offset) and currentTimeShiftSec is how far the same stream instant moved in currentTime between the cut and the hand-back (negative: it now sits earlier). applied=false with a reason means no PDT sample was available at the hand-back, so the anchor-based target applied. Context also carries breakId and computedTarget. |
+| `DA-RESUME-PDT-LANDED` | playback | info | timebase: 'wallclock', all platforms — where a Program-Date-Time resume landed, measured on the stream's own clock from the first position sample after the hand-back: errorSec is the PDT content resumed at minus the break end (negative: content resumed before the break end, so the stream's own break is shown; positive: post-break content was skipped). Context carries breakId, landingPdt (the break end), landedPdt, landedAt (currentTime) and sinceHandBackSec; reason when no sample carried a PDT within 2s. Report-only: the SDK does not correct the position from it. |
 | `DA-RESUME-CUE-END` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS, web and Android — the stream's matched type=cue_end replaced the computed resume target: the slate under the ad ends there, not at cue plus the advertised duration (150.206s for a 150s break on NFL Channel), and the player can remap its timeline while content is held, so the cue_end is reported in the current mapping. Context carries breakId, computedTarget, cueEndTarget, deltaSec (cueEndTarget - computedTarget), stage (hold, playing or hand-back; Android: always hand-back) and corrected (whether an in-buffer correction seek ran). Only a policy that resumes at the break end is replaced; otherwise applied=false and only the delta is reported. |
 | `DA-RESUME-CUE-END-LATE` | playback | info | ptsSource: 'anvatoCue', iOS/tvOS and Android — the break's type=cue_end was matched only after the hand-back. When it is more than 1s ahead of the playhead and buffered, content is seeked forward to it once (corrected=true); content is never seeked backward. Context carries breakId, cueEndTarget, currentTime, deltaSec (cueEndTarget - currentTime) and corrected. |
 | `DA-RESUME-CATCHUP` | playback | info | Content began playing behind the ad to reach its resume point. Context carries breakId, startPos, target, remainingAdSec, publishedEnd and clampedStart — clampedStart true means the stream had not published the ideal start position, so playback began late and the alignment loop must make up the difference (the zero-live-headroom case). Its ABSENCE on a live break that resumed short means catch-up never ran at all, which is a different fault from it running and falling short. |

package/ai/reference/features-overview.md

@@ -146,6 +146,15 @@ are preserved; the delivery mode pinned at session start is kept. The applicatio
 receives one `adchannelchange` event (`previousChannelId`, `channelId`, `reason`,
 `manifestUrl`) after the re-alignment. Web SDK only for now.
 
+## External provider parameters
+
+Use `getExternalVendorConfiguration()` to read the current macro-resolved
+parameters for every external provider, or pass an exact provider name such as
+`mediakind` to read one. Read the values just before calling the external
+system. `externalvendorconfigurationchange` fires when an adopted manifest
+adds, removes, or changes a provider's parameter template, including the first
+manifest. A macro-value change alone does not emit the event.
+
 ## Diagnostics
 
 The SDK emits structured `DiagnosticEvent`s (via `onDiagnostic`) and can export

package/ai/reference/knowledge-base.md

@@ -72,6 +72,16 @@ also restart with the new manifest's ids once the switch is applied.
 **Fix:** Nothing when the backend re-pointed the stream on purpose. Repeated
 flips between channels indicate an unstable manifest source.
 
+## External provider parameters
+
+Call `getExternalVendorConfiguration()` to retrieve all current provider
+configurations, or pass a provider name such as `mediakind` for one
+configuration. The returned `assetParameters` include current macro values.
+Read them immediately before passing them to the external system.
+`externalvendorconfigurationchange` is emitted when a newly adopted manifest
+adds, removes, or changes a provider's template, including the first manifest;
+macro-value changes alone do not emit it.
+
 ## DA-MANIFEST-SIGNATURE-INVALID
 
 **Cause:** The break-manifest response failed detached-JWS signature
@@ -625,6 +635,59 @@ when no beacon arrived within 15s. **Fix:** None for a single break. Unlike
 `DA-RESUME-LANDED` it is not measured in currentTime, so a timeline remap
 cannot hide in it.
 
+## DA-RESUME-PDT-MAP
+
+**Cause:** Informational (all platforms, `timebase: 'wallclock'`). The live resume
+point — the manifest `start + duration` — was placed through the stream's
+Program Date Time as the content player reports it now, so a currentTime
+re-anchored by a seek during the break cannot move it. Reported when the run-up
+first reads it and whenever it moves by 0.1s or more (`remapped: true`).
+`context` carries `breakId`, `target`, `landingPdt`, `pdtOffsetSec`,
+`currentTime`, `remapped`, `computedTarget` and `deltaSec`. **Fix:** None
+needed. A large `deltaSec` is the player's timeline having moved during the
+break, which this mapping corrects. A stream without Program Date Time never
+reports it and keeps the pause-position resume.
+
+## DA-RESUME-PDT-CORRECTED
+
+**Cause:** Informational (all platforms, `timebase: 'wallclock'`). Once per break
+at the hand-back of a break anchored on the Program Date Time: whether the
+stream clock placed the resume (`applied`), `correctionSec` from the anchor
+target (`computedTarget`) and `currentTimeShiftSec`, how far currentTime moved
+against the stream during the break. `context` also carries `breakId`,
+`pdtTarget` and, when not applied, `reason`. **Fix:** None needed. A large
+`currentTimeShiftSec` is a player timeline re-anchor the stream clock corrected.
+`applied: false` means no Program Date Time sample was available at the
+hand-back; if frequent, check that the stream carries
+`EXT-X-PROGRAM-DATE-TIME` and that the adapter exposes `programDateTime`.
+
+## DA-RESUME-PDT-LANDED
+
+**Cause:** Informational (all platforms, `timebase: 'wallclock'`). Where a
+Program-Date-Time resume landed on the stream clock, from the first position
+sample after the hand-back. `errorSec` is the landed Program Date Time minus
+the break end: negative means content resumed before the break end (that much
+of the stream's own break shown), positive means post-break content was
+skipped. `context` carries `breakId`, `landingPdt`, `landedPdt`, `landedAt`,
+`errorSec` and `sinceHandBackSec`; `reason` when no sample carried a Program
+Date Time within 2s. **Fix:** None within 0.5s. A larger value next to a
+`DA-RESUME-TARGET-CLAMPED` means the live window could not reach the resume
+point.
+
+## DA-BREAK-CUT-LATE
+
+**Cause:** Warning (all platforms, `timebase: 'wallclock'`). Content was cut more
+than 0.5s after the break's manifest start on the stream's Program Date Time
+(`lateSec`), so the viewer saw the stream's own break instead of the ad until
+then. The replaced window is not affected: the resume is anchored on the
+manifest start whatever the cut landed on. `context` carries `breakId`,
+`lateSec`, `start`, `cutPdt`, `cutAt`, `anchor` and, on iOS/tvOS and Android,
+`waitedForAdMs` — how long the cut waited for the ad's first frame under the
+cross-fade. **Fix:** Check that the break was prepared 8s ahead
+(`DA-PRELOAD-PATH`; a shorter manifest publication lead leaves no time) and, on
+iOS/tvOS, that the first-frame warm-up rendered a frame (`firstFrame: true`).
+A value of several seconds points at the pod request or the creative.
+
 ## DA-PRELOAD-FAILED
 
 **Cause:** Preloading the next ad failed; the asset will load on demand at break
@@ -646,7 +709,9 @@ from timings.
 
 **Cause:** Informational, emitted per preloaded break. States the preload path
 actually taken for the break's ad in `context.path`: `parallel` (buffered into
-the attached ad player), `single-decoder` (cache warm + detached prefetch) or
+the attached ad player), `single-decoder` (cache warm + detached prefetch),
+`first-frame` (iOS/tvOS: warmed up on the ad player itself to its first frame,
+then paused on it; `firstFrame` says whether the frame rendered) or
 `none` (no pre-break activity — cold-start baseline / opt-out).
 `context.creative` classifies the creative container: `stream` (HLS/DASH,
 MSE-eligible — real pre-buffering is possible) vs `progressive` (MP4/WebM,
@@ -1027,6 +1092,45 @@ scenario, capture the diagnostic stream too: the bounded export may no longer re
 earlier override. Repeated starts of the same completed break point to content restoration
 being mistaken for a viewer rewind, not necessarily to a missing PiP entry.
 
+## DA-PIP-HANDOFF
+
+**Cause:** iOS only. Records which route the ad takes onto the picture-in-picture window.
+`context.route` is `layer-swap` — the default: the renderer finds the `AVPlayerLayer` the
+window presents under the content view and re-points its `.player` at the SDK's ad player,
+so the ad reaches the window with no source reload and content keeps its item — or
+`borrow`, the fallback for when no presented layer can be identified (no content view
+handed to the renderer, or an ambiguous layer tree), which plays the ad through the
+content player itself and restores its source afterwards. `context.layers` inventories
+the `AVPlayerLayer`s found and the player each carries. **Fix:** Informational. If you
+expected `layer-swap` but see `borrow`, check that the host actually attached its player
+surface to the view handed to the renderer before the break starts; a `borrow` on a
+stream the adapter cannot restore would already have been refused as
+`DA-SHARED-ELEMENT-UNSUPPORTED`. Non-fatal.
+
+## DA-PIP-LAYER-SWAP
+
+**Cause:** iOS only. Read-back logged a few hundred milliseconds after a PiP layer-swap:
+whether the presented layer still points at the ad player (`context.held`), plus a
+`layers` inventory. **Fix:** `held: false` means something reverted the re-point — the
+host player rebuilding its internal layer on a source change is the usual suspect, since
+the window was bound to the old layer object. The window then shows content while the ad
+plays inline; the `DA-PIP-PRESENTED` trace shows which player actually landed on the
+layer. Non-fatal, informational.
+
+## DA-PIP-PRESENTED
+
+**Cause:** iOS only. Debug trace of the exact signal AVKit's PiP chrome reacts to during
+a layer-swap: which player the presented layer points at (`owner`: `ad`, `content` or
+`other`) and its `timeControlStatus` transitions, plus ad-item ends observed while the
+layer was presented (`errored`, `reachedEnd`, `adStatus`). **Fix:** None — it is the
+timeline to read when a controls flash or a stalled window is reported. A `paused` or
+`waiting` status landing on the presented player is what re-raises the window chrome,
+which is why the swap waits for `readyToPlay` + `playing`, pauses content only after the
+flip, and defers the exit hand-back past the close morph. `reachedEnd: true` followed by
+`presented layer → content player` is the healthy last-asset path; `reachedEnd: false`
+is a forced break cut and intentionally keeps the ad on the layer until break end.
+Non-fatal.
+
 ## DA-IMAGE-LOAD-FAILED
 
 **Cause:** An image the renderer needed — a `double`/`lshape_ad` companion, an
@@ -1061,6 +1165,14 @@ Common causes: wrong `networkCode`/`customAssetKey`, IMA SDK not loaded, or no
 the IMA SDK is loaded, the `networkCode` and `customAssetKey` are correct, and your
 content adapter exposes `videoElement`. Inspect `context.message`.
 
+## DA-GAM-START-DEFERRED
+
+**Cause:** Informational. The SGAI IMA stream request was deferred because the
+manifest's positive `adStartDelay` has not yet been played. `context.adStartDelaySec`
+reports the configured delay. **Fix:** None needed. This confirms the ad-free start
+is active; content must advance for the delay to elapse. If IMA does not start after
+that, check `DA-GAM-SESSION-FAILED`.
+
 ## DA-GAM-CONFIG-RESOLVED
 
 **Cause:** Informational. The GAM stream identity for this session was read from the
@@ -1107,6 +1219,15 @@ stream ends; `adbreakend` fires once, at the real end of the pod.
 before the early end, and `context.remainingSec` the pod left. A recurring hit on one asset
 points at the pod's ad decisioning or IMA rather than the integration.
 
+## DA-GAM-DUPLICATE-METADATA
+
+**Cause:** Informational. The stream carried the same ad marker more than once at the
+same playback time (for example in both audio and video renditions of an fMP4 stream).
+The duplicate was not forwarded to IMA, so each ad lifecycle event fires once. The
+diagnostic is reported once per stream session; `context.startTime` identifies the cue
+time. **Fix:** No action is needed when duplicate markers are expected. Otherwise,
+remove duplicate markers from stream packaging.
+
 ## DA-VENDOR-CONFIG-UNKNOWN-TYPE
 
 **Cause:** Informational. The manifest carried `vendorConfiguration` entries whose
@@ -1115,6 +1236,20 @@ forward-compatibility rule. `context.types` names them. **Fix:** None needed —
 expected when a newer backend serves an older client. If the type is one you expect to
 be supported, check the SDK version.
 
+## DA-EXTERNAL-VENDOR-INVALID
+
+**Cause:** The manifest contained external `vendorConfiguration` entries with a
+blank provider or without an object-valued `assetParameters` map. Those entries were
+ignored; `context.count` gives the number rejected. **Fix:** Correct the provider and
+parameter map in the manifest. Non-string parameter values are discarded.
+
+## DA-EXTERNAL-VENDOR-DUPLICATE
+
+**Cause:** The manifest contained multiple valid external `vendorConfiguration`
+entries for the same provider. The first entry was kept; `context.providers` names
+the duplicates. Provider matching is case-sensitive. **Fix:** Combine the
+parameters into one entry per provider.
+
 ## DA-SSAI-SESSION-FAILED
 
 **Cause:** An SSAI (`mode: 'ssai'`) session failed to start. The SDK could not
@@ -1132,7 +1267,30 @@ on the first break-manifest fetch and is pinned for the rest of the session.
 `context.mode` is the resolved mode, `context.source` says whether it came from the
 manifest `delivery` rules (`manifest`) or an explicit constructor `mode` (`config`),
 and `context.ruleIndex` names the matching rule (`null` when no rule matched and the
-sgai default applied). **Fix:** No action needed.
+sgai default applied). `context.deviceProfile` records the detected device type,
+platform, OS and OS version when available. **Fix:** No action needed.
+
+## DA-TARGETING-VALUE-UNKNOWN
+
+**Cause:** A delivery rule, variant or asset URI targeting entry contains a
+`deviceType`, `platform` or `os` value this SDK does not recognize, so the entry
+does not match. `context.field` and `context.value` identify the value. **Fix:**
+Use a value from the manifest targeting schema, or update the SDK if the manifest
+intentionally uses a newer value.
+
+## DA-TARGETING-FIELD-UNKNOWN
+
+**Cause:** A targeting entry contains an unknown field, so it does not match.
+`context.field` identifies the field path, including nested `osVersion` keys.
+**Fix:** Correct a field-name typo, or update the SDK if the manifest uses a
+newer targeting field.
+
+## DA-TARGETING-INVALID
+
+**Cause:** An `osVersion` constraint is malformed or incomplete, such as missing
+`os`, having neither `min` nor `max`, or using a non-decimal bound. The targeted
+entry does not match. `context.field` and optional `context.value` identify the
+problem. **Fix:** Include `os` and at least one decimal `min` or `max` version.
 
 ## DA-DELIVERY-MODE-OVERRIDDEN
 
@@ -1326,8 +1484,8 @@ resolve — the name is not a built-in (`$OPTIVIEW_USER_AGENT$`,
 `$OPTIVIEW_PLAYER_WIDTH$`, `$OPTIVIEW_PLAYER_HEIGHT$`,
 `$OPTIVIEW_BREAK_DURATION_MS$`, `$OPTIVIEW_BREAK_DURATION_SECONDS$`; matching is
 exact and case-sensitive), or the value is unavailable on this platform (iOS has
-no user agent; the break duration is unknown when neither the asset nor the
-break declares one). The parameter is still sent with the unresolved token kept
+no user agent; the break duration is unknown on the GAM stream request, before
+any break, or when neither the asset nor the break declares one). The parameter is still sent with the unresolved token kept
 literally, so the token is visible in the ad request (`context.key`,
 `context.macro`). **Fix:** Correct the macro name in the manifest, or register the name in
 `SessionConfig.assetParameterMacros` so your fixed value or callback supplies

package/dist/NativeVideoAdapter.d.ts

@@ -21,6 +21,8 @@ export declare class NativeVideoAdapter implements PlayerAdapter {
     private emittedCues;
     /** Target duration supplied by the SDK for the live startup distance; null when unknown. */
     private liveStartTargetDuration;
+    /** The `load()` / `recreateMediaPipeline()` in flight, which owns element errors until it settles. */
+    private activeOperation;
     constructor(videoElement: HTMLVideoElement);
     get currentTime(): number;
     get duration(): number;
@@ -128,6 +130,8 @@ export declare class NativeVideoAdapter implements PlayerAdapter {
     private teardownMetadataListener;
     /** Map a native metadata cue (Safari ID3 `DataCue`) onto a {@link TimedMetadataCue}. */
     private toCue;
+    private beginOperation;
+    private endOperation;
     private setupVideoListeners;
     private emit;
 }

package/dist/NativeVideoAdapter.js

@@ -1 +1 @@
-export class NativeVideoAdapter{constructor(e){this.boundHandlers=new Map,this.eventListeners=new Map,this.cueTracks=[],this.emittedCues=new WeakSet,this.liveStartTargetDuration=null,this.video=e,this.setupVideoListeners(),this.setupMetadataListener()}get currentTime(){return this.video.currentTime}get duration(){return this.video.duration}get paused(){return this.video.paused}get muted(){return this.video.muted}set muted(e){this.video.muted=e}get volume(){return this.video.volume}set volume(e){this.video.volume=e}get videoElement(){return this.video}get playbackReady(){return this.video.readyState>=HTMLMediaElement.HAVE_CURRENT_DATA&&!this.video.seeking}get programDateTime(){const e=this.webKitStartDate();if(!e)return null;if(this.video.readyState<HTMLMediaElement.HAVE_METADATA)return null;const t=e.call(this.video);return t instanceof Date&&t.getTime()>0?new Date(t.getTime()+1e3*this.video.currentTime):null}get liveEdge(){const e=this.liveStartTargetDuration,t=this.video.seekable;if(null===e||!this.webKitStartDate()||this.video.duration!==1/0||!t?.length)return null;const i=t.end(t.length-1);return Number.isFinite(i)?i+3*e:null}requestLiveStartOffset(e,t){const i=t;return this.liveStartTargetDuration=null!==e&&null!==i&&Number.isFinite(i)&&i>0?i:null,!1}webKitStartDate(){const e=this.video.getStartDate;return"function"==typeof e?e:void 0}get supportsParallelBuffering(){return!0}pause(){this.video.pause()}async play(){await this.video.play()}seek(e){this.video.currentTime=e}get sourceUrl(){return this.video.currentSrc||this.video.src||null}async load(e){return new Promise((t,i)=>{const r=()=>{n(),t()},s=()=>{n(),i(new Error("Native video load error"))},n=()=>{this.video.removeEventListener("loadedmetadata",r),this.video.removeEventListener("error",s)};this.video.addEventListener("loadedmetadata",r),this.video.addEventListener("error",s),this.video.preload="auto",this.video.src=e,this.video.load()})}unload(){this.video.removeAttribute("src"),this.video.load()}recreateMediaPipeline(e){const t=this.sourceUrl;return t?new Promise((i,r)=>{const s=()=>{a(),this.video.currentTime=e.startTime,i()},n=()=>{a(),r(new Error("Native pipeline recreate error"))},a=()=>{this.video.removeEventListener("loadedmetadata",s),this.video.removeEventListener("error",n)};this.video.addEventListener("loadedmetadata",s),this.video.addEventListener("error",n),this.video.removeAttribute("src"),this.video.load(),this.video.src=t,this.video.load()}):Promise.reject(new Error("Native pipeline recreate: no source URL"))}async preload(e){if("undefined"!=typeof document)return new Promise(t=>{const i=document.createElement("video");i.preload="metadata",i.muted=!0;let r=!1;const s=()=>{r||(r=!0,clearTimeout(n),i.removeAttribute("src"),i.load(),t())},n=setTimeout(s,8e3);i.addEventListener("loadedmetadata",s,{once:!0}),i.addEventListener("error",s,{once:!0}),i.src=e})}on(e,t){this.eventListeners.has(e)||this.eventListeners.set(e,new Set),this.eventListeners.get(e).add(t)}off(e,t){this.eventListeners.get(e)?.delete(t)}destroy(){for(const[e,t]of this.boundHandlers)this.video.removeEventListener(e,t);this.boundHandlers.clear(),this.teardownMetadataListener(),this.eventListeners.clear()}setupMetadataListener(){const e=this.video.textTracks;if(!e||"function"!=typeof e.addEventListener)return;const t=e=>{this.emittedCues.has(e)||(this.emittedCues.add(e),this.emit("timedmetadata",this.toCue(e)))},i=e=>{const i=e.cues;if(i)for(let e=0;e<i.length;e++)t(i[e])},r=e=>{if("metadata"!==e.kind)return;e.mode="hidden";const r=()=>{const i=e.activeCues;if(i)for(let e=0;e<i.length;e++)t(i[e])};e.addEventListener("cuechange",r),this.cueTracks.push({track:e,handler:r}),i(e)},s=e=>{const t=e.track;t&&r(t)};this.addTrackHandler=s,e.addEventListener("addtrack",s);const n=()=>{for(const{track:e}of this.cueTracks)i(e)};this.cueScanHandler=n,this.video.addEventListener("timeupdate",n);for(let t=0;t<e.length;t++)r(e[t])}teardownMetadataListener(){const e=this.video.textTracks;this.addTrackHandler&&e?.removeEventListener&&(e.removeEventListener("addtrack",this.addTrackHandler),this.addTrackHandler=void 0),this.cueScanHandler&&(this.video.removeEventListener("timeupdate",this.cueScanHandler),this.cueScanHandler=void 0);for(const{track:e,handler:t}of this.cueTracks)e.removeEventListener("cuechange",t);this.cueTracks=[],this.emittedCues=new WeakSet}toCue(e){const t={type:"id3",startTime:e.startTime,endTime:e.endTime},i=e.value;if(i?.key){const e="string"==typeof(r=i.data)?r:null==r?"":"[object ArrayBuffer]"===Object.prototype.toString.call(r)?(new TextDecoder).decode(new Uint8Array(r)):ArrayBuffer.isView(r)?(new TextDecoder).decode(new Uint8Array(r.buffer,r.byteOffset,r.byteLength)):String(r);t.frames={[i.key]:e},"string"==typeof i.info&&i.info&&(t.description=i.info),e&&(t.messageData=e)}var r;return t}setupVideoListeners(){const e=["timeupdate","ended","error","seeked","volumechange","waiting","playing","pause"];for(const t of e){const e=()=>{this.emit(t,"error"===t?this.video.error:void 0)};this.video.addEventListener(t,e),this.boundHandlers.set(t,e)}}emit(e,t){const i=this.eventListeners.get(e);if(i)for(const e of i)try{e(t)}catch(e){console.error("[NativeVideoAdapter] Event handler error:",e)}}}
+import{nativeMediaLoadError as e}from"./nativeMediaLoadError";export class NativeVideoAdapter{constructor(e){this.boundHandlers=new Map,this.eventListeners=new Map,this.cueTracks=[],this.emittedCues=new WeakSet,this.liveStartTargetDuration=null,this.activeOperation=null,this.video=e,this.setupVideoListeners(),this.setupMetadataListener()}get currentTime(){return this.video.currentTime}get duration(){return this.video.duration}get paused(){return this.video.paused}get muted(){return this.video.muted}set muted(e){this.video.muted=e}get volume(){return this.video.volume}set volume(e){this.video.volume=e}get videoElement(){return this.video}get playbackReady(){return this.video.readyState>=HTMLMediaElement.HAVE_CURRENT_DATA&&!this.video.seeking}get programDateTime(){const e=this.webKitStartDate();if(!e)return null;if(this.video.readyState<HTMLMediaElement.HAVE_METADATA)return null;const t=e.call(this.video);return t instanceof Date&&t.getTime()>0?new Date(t.getTime()+1e3*this.video.currentTime):null}get liveEdge(){const e=this.liveStartTargetDuration,t=this.video.seekable;if(null===e||!this.webKitStartDate()||this.video.duration!==1/0||!t?.length)return null;const i=t.end(t.length-1);return Number.isFinite(i)?i+3*e:null}requestLiveStartOffset(e,t){const i=t;return this.liveStartTargetDuration=null!==e&&null!==i&&Number.isFinite(i)&&i>0?i:null,!1}webKitStartDate(){const e=this.video.getStartDate;return"function"==typeof e?e:void 0}get supportsParallelBuffering(){return!0}pause(){this.video.pause()}async play(){await this.video.play()}seek(e){this.video.currentTime=e}get sourceUrl(){return this.video.currentSrc||this.video.src||null}async load(t){const i=this.beginOperation();return new Promise((r,n)=>{const s=()=>{o(),this.endOperation(i),r()},a=()=>{o(),e("Native video load error",t,this.video.error).then(e=>{this.endOperation(i),n(e)})},o=()=>{this.video.removeEventListener("loadedmetadata",s),this.video.removeEventListener("error",a)};this.video.addEventListener("loadedmetadata",s),this.video.addEventListener("error",a),this.video.preload="auto",this.video.src=t,this.video.load()})}unload(){this.activeOperation=null,this.video.removeAttribute("src"),this.video.load()}recreateMediaPipeline(t){const i=this.sourceUrl;if(!i)return Promise.reject(new Error("Native pipeline recreate: no source URL"));const r=this.beginOperation();return new Promise((n,s)=>{const a=()=>{d(),this.endOperation(r),this.video.currentTime=t.startTime,n()},o=()=>{d(),e("Native pipeline recreate error",i,this.video.error).then(e=>{this.endOperation(r),s(e)})},d=()=>{this.video.removeEventListener("loadedmetadata",a),this.video.removeEventListener("error",o)};this.video.addEventListener("loadedmetadata",a),this.video.addEventListener("error",o),this.video.removeAttribute("src"),this.video.load(),this.video.src=i,this.video.load()})}async preload(e){if("undefined"!=typeof document)return new Promise(t=>{const i=document.createElement("video");i.preload="metadata",i.muted=!0;let r=!1;const n=()=>{r||(r=!0,clearTimeout(s),i.removeAttribute("src"),i.load(),t())},s=setTimeout(n,8e3);i.addEventListener("loadedmetadata",n,{once:!0}),i.addEventListener("error",n,{once:!0}),i.src=e})}on(e,t){this.eventListeners.has(e)||this.eventListeners.set(e,new Set),this.eventListeners.get(e).add(t)}off(e,t){this.eventListeners.get(e)?.delete(t)}destroy(){for(const[e,t]of this.boundHandlers)this.video.removeEventListener(e,t);this.boundHandlers.clear(),this.teardownMetadataListener(),this.eventListeners.clear()}setupMetadataListener(){const e=this.video.textTracks;if(!e||"function"!=typeof e.addEventListener)return;const t=e=>{this.emittedCues.has(e)||(this.emittedCues.add(e),this.emit("timedmetadata",this.toCue(e)))},i=e=>{const i=e.cues;if(i)for(let e=0;e<i.length;e++)t(i[e])},r=e=>{if("metadata"!==e.kind)return;e.mode="hidden";const r=()=>{const i=e.activeCues;if(i)for(let e=0;e<i.length;e++)t(i[e])};e.addEventListener("cuechange",r),this.cueTracks.push({track:e,handler:r}),i(e)},n=e=>{const t=e.track;t&&r(t)};this.addTrackHandler=n,e.addEventListener("addtrack",n);const s=()=>{for(const{track:e}of this.cueTracks)i(e)};this.cueScanHandler=s,this.video.addEventListener("timeupdate",s);for(let t=0;t<e.length;t++)r(e[t])}teardownMetadataListener(){const e=this.video.textTracks;this.addTrackHandler&&e?.removeEventListener&&(e.removeEventListener("addtrack",this.addTrackHandler),this.addTrackHandler=void 0),this.cueScanHandler&&(this.video.removeEventListener("timeupdate",this.cueScanHandler),this.cueScanHandler=void 0);for(const{track:e,handler:t}of this.cueTracks)e.removeEventListener("cuechange",t);this.cueTracks=[],this.emittedCues=new WeakSet}toCue(e){const t={type:"id3",startTime:e.startTime,endTime:e.endTime},i=e.value;if(i?.key){const e="string"==typeof(r=i.data)?r:null==r?"":"[object ArrayBuffer]"===Object.prototype.toString.call(r)?(new TextDecoder).decode(new Uint8Array(r)):ArrayBuffer.isView(r)?(new TextDecoder).decode(new Uint8Array(r.buffer,r.byteOffset,r.byteLength)):String(r);t.frames={[i.key]:e},"string"==typeof i.info&&i.info&&(t.description=i.info),e&&(t.messageData=e)}var r;return t}beginOperation(){const e=Symbol("native-operation");return this.activeOperation=e,e}endOperation(e){this.activeOperation===e&&(this.activeOperation=null)}setupVideoListeners(){const e=["timeupdate","ended","error","seeked","volumechange","waiting","playing","pause"];for(const t of e){const e=()=>{"error"!==t?this.emit(t,void 0):null===this.activeOperation&&this.emit(t,this.video.error)};this.video.addEventListener(t,e),this.boundHandlers.set(t,e)}}emit(e,t){const i=this.eventListeners.get(e);if(i)for(const e of i)try{e(t)}catch(e){console.error("[NativeVideoAdapter] Event handler error:",e)}}}

package/dist/nativeMediaLoadError.d.ts

@@ -0,0 +1,14 @@
+/** A native element load failure with its `MediaError` `code`, which core classifies. */
+export declare class NativeMediaLoadError extends Error {
+    readonly code: number | undefined;
+    constructor(prefix: string, code: number | undefined, detail?: string);
+}
+type ProbeResult = 'unreachable' | 'reachable' | 'unknown';
+/**
+ * One bounded request to tell a missing or unreachable resource from unplayable media. The
+ * element reports both as `MEDIA_ERR_SRC_NOT_SUPPORTED` before it has any data.
+ */
+export declare function probeMediaUrl(url: string, timeoutMs?: number): Promise<ProbeResult>;
+/** The load error for a failed element, refining an unsupported-source code with {@link probeMediaUrl}. */
+export declare function nativeMediaLoadError(prefix: string, url: string, mediaError: MediaError | null): Promise<NativeMediaLoadError>;
+export {};

package/dist/nativeMediaLoadError.js

@@ -0,0 +1 @@
+export class NativeMediaLoadError extends Error{constructor(e,r,o){super(`${e}${void 0!==r?` (code ${r})`:""}${o?`: ${o}`:""}`),this.code=r,this.name="NativeMediaLoadError"}}export async function probeMediaUrl(e,r=2e3){if("function"!=typeof fetch||!/^https?:/i.test(e))return"unknown";const o="function"==typeof AbortController?new AbortController:null;let t=null;const a=new Promise(e=>{t=setTimeout(()=>{o?.abort(),e("unknown")},r)}),n=fetch(e,{credentials:"omit",cache:"no-store",...o?{signal:o.signal}:{}}).then(e=>(e.body?.cancel().catch(()=>{}),e.status>=400?"unreachable":"reachable"),()=>o?.signal.aborted?"unknown":"unreachable");try{return await Promise.race([n,a])}finally{t&&clearTimeout(t)}}export async function nativeMediaLoadError(e,r,o){const t="number"==typeof o?.code?o.code:void 0,a=o?.message||void 0;if(4!==t)return new NativeMediaLoadError(e,t,a);return"unreachable"===await probeMediaUrl(r)?new NativeMediaLoadError(e,2,a??"resource not reachable"):new NativeMediaLoadError(e,t,a)}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "OptiView Ads SDK entry package - OptiViewAds with a default HLS.js ad player (native fallback)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,8 +44,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@dolby-optiview/ads-sdk-adapter-hlsjs": "^1.1.1",
-    "@dolby-optiview/ads-sdk-core": "^1.1.1"
+    "@dolby-optiview/ads-sdk-adapter-hlsjs": "^1.2.0",
+    "@dolby-optiview/ads-sdk-core": "^1.2.0"
   },
   "peerDependencies": {
     "hls.js": "^1.0.0"