@dolby-optiview/ads-sdk 1.3.0 → 1.5.1

package/ai/reference/error-codes.md

@@ -9,6 +9,9 @@ of the public contract and are never renamed.
 
 | Code | Category | Level | Meaning |
 |---|---|---|---|
+| `DA-SNAPBACK-APPLIED` | break | info | Viewer seek corrected to an unplayed VOD snapback break. context: breakId, target, resumePosition (seek-over only). |
+| `DA-SNAPBACK-ABANDONED` | break | warn | VOD snapback correction abandoned after one retry or because the break became ineligible. context: breakId, reason. |
+| `DA-SNAPBACK-NOT-APPLIED` | break | debug | Viewer seek was not eligible for VOD snapback. context: reason, breakId (when known). |
 | `DA-SESSION-STARTED` | session | info | Monetization session started; manifest polling began. context: manifestUrl (stitcherUrl in SSAI mode), reported verbatim. |
 | `DA-SESSION-ENDED` | session | info | Monetization session ended; polling and scheduling stopped. |
 | `DA-ASSET-PARAMETERS-UPDATED` | session | info | The break manifest's session-level asset parameters changed; the merged parameters were pushed to the active GAM stream. context: source ('manifest'), keys (parameter names only, never values). |
@@ -37,7 +40,7 @@ of the public contract and are never renamed.
 | `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. A break-to-break switch runs from the outgoing ad's end to the incoming ad's first frame and adds path (queued, late-queued or cold) and, when the incoming ad was buffered, leadMs. On web an ad-to-ad switch adds path (queued or cold) and leadMs too. |
 | `DA-BREAK-CHAIN` | chaining | info | Summary of one chain of back-to-back breaks, emitted once when content plays again (or the chain is flushed): chainId, per break its id, scheduledStart, plannedDurationSec, beganAtMs, endedAtMs, playedSec, announcedDuringChain and path, per switch its gapMs and path, contentResumeMs and totalMs. |
-| `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-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. On web, an ad shown before its first frame reports reason shown-before-frame with visibleGapMs, the time on screen without a picture. |
 | `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. |

package/ai/reference/knowledge-base.md

@@ -12,6 +12,18 @@ the sequence leading up to a failure.
 
 ---
 
+## DA-SNAPBACK-APPLIED
+
+Expected VOD seek protection: the first crossed unplayed playable snapback break was selected. Compare `target` with the break start and `resumePosition` with the original seek-over target. Confirm the landing and balanced break lifecycle; a correction request alone does not prove playback succeeded. Seek-into uses normal resume policy.
+
+## DA-SNAPBACK-ABANDONED
+
+The content player did not land after one corrective retry, or the selected break became ineligible. Check the adapter's seek implementation, seekable range and competing host seeks. The SDK releases the correction instead of trapping playback in a loop.
+
+## DA-SNAPBACK-NOT-APPLIED
+
+Check the diagnostic `reason`, VOD mediatime scheduling, `controls.snapback`, playable variants and whether the break already started in this session. Live, event-triggered, SSAI/SSB and excluded single-decoder web platforms are unchanged.
+
 ## DA-SESSION-STARTED
 
 Informational. The session started and manifest polling began. Use it to confirm

package/ai/reference/playeradapter.contract.md

@@ -16,6 +16,8 @@ and creates the matching native adapter. See `react-native-overview.md`.
 
 ## Events
 
+For VOD snapback, prefer the SDK's `seek()` entry point: it plans the correction before moving the player. External content seeks use `seeked`, or position jumps greater than two seconds when a host has no direct notification (AVPlayer host controls). Corrective seeks must land at the break start: Media3 uses exact seek parameters and AVPlayer uses zero tolerances. SDK corrections are suppressed as new viewer intent. Only playable mediatime-scheduled client-side VOD breaks participate; TV web, live, PTS/wallclock, event-triggered, SSAI and SSB are excluded. Seek-over resumes at the original target after the full break; seek-into uses normal resume policy.
+
 `PlayerAdapterEvent` is exactly these seven strings. An adapter MUST forward all
 of them to handlers registered via `on()`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dolby-optiview/ads-sdk",
-  "version": "1.3.0",
+  "version": "1.5.1",
   "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.3.0",
-    "@dolby-optiview/ads-sdk-core": "^1.3.0"
+    "@dolby-optiview/ads-sdk-adapter-hlsjs": "^1.5.1",
+    "@dolby-optiview/ads-sdk-core": "^1.5.1"
   },
   "peerDependencies": {
     "hls.js": "^1.0.0"