PlayerAdapter Interface

Any adapter must implement all properties and methods below. The interface is imported from @dolby-optiview/ads-sdk-core.

import type {
  PlayerAdapter,
  PlayerAdapterEvent,
  PlayerAdapterEventHandler,
} from '@dolby-optiview/ads-sdk-core';

// Events the adapter must support
type PlayerAdapterEvent = 'timeupdate' | 'ended' | 'error' | 'seeked' | 'volumechange';

interface PlayerAdapter {
  /** Current playback position in seconds. */
  readonly currentTime: number;

  /** Total duration in seconds (Infinity for live streams). */
  readonly duration: number;

  /** True when playback is paused. */
  readonly paused: boolean;

  /** Whether the player is muted. */
  muted: boolean;

  /** Volume level in the range [0, 1]. */
  volume: number;

  /** Current Program Date Time from the HLS manifest.
   *  Required for wallclock-timebase break matching on live streams.
   *  Return null if not available. */
  readonly programDateTime: Date | null;

  /** Pause playback. Called by SDK at break start. */
  pause(): void;

  /** Resume playback. Called by SDK at break end. */
  play(): Promise<void>;

  /** Seek to a position in seconds.
   *  Required for SDK snapback enforcement during locked breaks. */
  seek(time: number): void;

  /** Load a media URL and resolve when ready to play (manifest parsed).
   *  Used for preloading ad content 5 seconds before break start. */
  load(url: string): Promise<void>;

  /** Subscribe to a player event. */
  on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;

  /** Unsubscribe from a player event. */
  off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void;

  /** Release all resources. Called when SDK is destroyed. */
  destroy(): void;

  /** Best-effort quality constraint used while content continues behind a DAR break.
   *  Pass `null` to restore the exact selection in force before the first set. */
  setVideoQuality?(quality: 'lowest' | null): boolean;

  // ── optional ──────────────────────────────────────────────────────────────

  /** Stop driving the `<video>` without tearing the player down, so the SDK can
   *  play an ad through that same element (shared-element insertion). Resolve only
   *  once the element is genuinely free: an asynchronous teardown that lands after
   *  this resolves will reset the ad engine's MediaSource and the ad never starts.
   *  The SDK hands the element back at break end by calling `load()` again on this
   *  same adapter, so this must NOT destroy the player. Omit it if your engine is
   *  happy to share the element (hls.js is). */
  releaseMediaElement?(): void | Promise<void>;

  /** Whether the content is LIVE, as the engine itself understands it.
   *  Return null when unsure — the SDK falls back to the duration test.
   *  Skip these three live members entirely unless you support live DVR. */
  readonly isLive?: boolean | null;

  /** The furthest position a seek will actually STICK on live content — the
   *  engine pulls back anything closer to the live edge. Return null when
   *  unsure (safe: the SDK then does not clamp); never guess. */
  readonly maxLiveSeekPosition?: number | null;

  /** Where the media currently ENDS, per the ENGINE — only needed when the
   *  <video> element's own seekable range is unreliable (THEOplayer reports
   *  an unbounded sentinel on live). Return null / omit when unsure. */
  readonly seekableEnd?: number | null;

  /** Release the media you hold without destroying the adapter — called on the
   *  AD adapter at break end. May return a promise; when it does the SDK awaits
   *  it before resuming content. */
  unload?(): void | Promise<void>;

  /** Tear down and rebuild the media pipeline (MediaSource / source buffers)
   *  for the CURRENT source, positioned at `startTime` seconds — called on the
   *  CONTENT adapter at break end when `adBreakContentRecovery` resolves to
   *  `recreate` (VIZIO SmartCast). Resolve once metadata for the rebuilt
   *  pipeline is available; reject on failure — the SDK then falls back to
   *  seek + play. Omit when the engine has no such operation. */
  recreateMediaPipeline?(options: { startTime: number }): Promise<void>;
}

HLS.js Adapter

The official HLS.js adapter is available as a separate package.

Install

npm install @dolby-optiview/ads-sdk-adapter-hlsjs hls.js

Requirements

• One Hls instance for content. The ad HLS instance is created inside createAdAdapter.
• One <video> element for content. The ad <video> is created by your factory inside the SDK-provided container.
• HLS streams must contain EXT-X-PROGRAM-DATE-TIME tags for wallclock-timebase channels.

Full setup example

import Hls from 'hls.js';
import { OptiViewAds } from '@dolby-optiview/ads-sdk-core';
import { HlsJsAdapter } from '@dolby-optiview/ads-sdk-adapter-hlsjs';

const video = document.getElementById('video') as HTMLVideoElement;

const hls = new Hls();
hls.attachMedia(video);

const sdk = new OptiViewAds({
  player: new HlsJsAdapter(hls, video),
  container: document.getElementById('container'),
  createAdAdapter: (adContainer) => {
    const adVideo = document.createElement('video');
    adContainer.appendChild(adVideo);
    const adHls = new Hls();
    adHls.attachMedia(adVideo);
    return new HlsJsAdapter(adHls, adVideo);
  },
  gam: {}, // presence enables GAM; the identity comes from the manifest
});

sdk.addEventListener('adbreakbegin', (e) => {
  console.log('Ad break', e.break.id, 'started —', e.break.duration, 's');
});
sdk.addEventListener('adbreakend', () => {
  console.log('Content resuming');
});

await sdk.startSession({
  manifestUrl: 'https://manifest.example.com/v1/your-org/channels/your-channel',
});

hls.loadSource('https://example.com/live.m3u8');
video.play();

Seek & seeked event

The HLS.js adapter implements seek(time) by setting video.currentTime and forwards the native seeked video event. This enables the SDK to detect and correct unexpected seeks during locked ad breaks.

PDT (Program Date Time)

The HLS.js adapter automatically tracks EXT-X-PROGRAM-DATE-TIME from the manifest and exposes it via programDateTime. This is used by the SDK to match wallclock-timebase breaks against the live stream position.

Cleanup

// When the player is torn down:
sdk.destroy(); // also destroys the internal ad player
hls.destroy();

Shaka Player Adapter

The official Shaka Player adapter is available as a separate package. It supports HLS and DASH streams and extracts programDateTime from Shaka's presentation timeline for live streams.

Install

npm install @dolby-optiview/ads-sdk-adapter-shaka shaka-player

Requirements

• Shaka Player 4.x or 5.x
• Call shaka.polyfill.installAll() once before creating any shaka.Player instance

Full setup example

import shaka from 'shaka-player';
import { OptiViewAds } from '@dolby-optiview/ads-sdk-core';
import { ShakaAdapter } from '@dolby-optiview/ads-sdk-adapter-shaka';

// 1. Install Shaka polyfills (once per page)
shaka.polyfill.installAll();

// 2. Content player
const video = document.getElementById('video') as HTMLVideoElement;
const player = new shaka.Player(video);

// 3. SDK — pass Player WITHOUT video to avoid eager MediaSource init on the ad element
//    playerContainer is optional; SDK auto-wraps when omitted
const sdk = new OptiViewAds({
  player: new ShakaAdapter(player, video),
  container: document.getElementById('container'),
  createAdAdapter: (adContainer) => {
    const adVideo = document.createElement('video');
    adContainer.appendChild(adVideo);
    return new ShakaAdapter(new shaka.Player(), adVideo);
  },
});

// 5. Start session and load stream
await sdk.startSession({
  manifestUrl: 'https://manifest.example.com/v1/your-org/channels/your-channel',
});
await player.load('https://example.com/live.m3u8');
video.play();

PDT (Program Date Time)

For live HLS streams with EXT-X-PROGRAM-DATE-TIME, the Shaka adapter derives the wall-clock position from Shaka's PresentationTimeline.getInitialProgramDateTime() (the manifest's PDT anchor) combined with video.currentTime. This is used to match wallclock-timebase breaks.

In-stream timed metadata (ID3 / emsg)

The Shaka adapter forwards in-stream markers to the SDK as timedmetadata cues — used to relay ad-tracking metadata to IMA during SSAI, and to match Anvato in-stream break signaling when ptsSource: 'anvatoCue' is configured (see Configuration).

The adapter subscribes to three Shaka events:

Emsg cues keep their raw payload bytes, so Anvato signaling also works when the marker is a full ID3 GEOB tag wrapped in the standardized ID3-in-emsg carriage (https://aomedia.org/emsg/ID3 / Apple's https://developer.apple.com/streaming/emsg-id3) — the core unwraps the tag itself; the adapter just forwards the bytes.

The adapter emits parsed and presented for each marker. The SDK forwards raw ID3 bytes at parse time, so IMA schedules them by media time, and forwards frames-only markers at presentation time.

Two behaviours are specific to Shaka and handled inside the adapter:

• GEOB frames are decoded by the adapter, not by Shaka. shaka.util.Id3Utils has no GEOB decoder, so Shaka reports such frames with an empty description, a null MIME type and the whole undecoded frame body as data. The adapter parses that body itself so the cue carries the real description (Anvatos), mimeType (application/json) and payload (type=cue&pts=…). Players that already decode GEOB are passed through untouched.
• Anvato cues must be seen before their media time. An Anvato cue's media time is the break start, so a playhead-time-only subscription would learn it too late to arm and preload the break. Subscribing to metadataadded gives the adapter the same parse-time delivery HLS.js has.

Picture-in-picture on Safari

Safari cannot move a picture-in-picture window to a second <video>, so a break that starts in PiP plays the ad through Shaka's own element: the adapter detaches Shaka for the ad and re-attaches it with load() when the break ends. Keep the SDK's default ad engine for that element (omit createAdAdapter, or return defaultAdAdapter(container, sharedVideo) when the second argument is set). At break end the SDK first tells that ad engine to stand down without emptying the element, then reloads content through Shaka, so the window stays open and content resumes where it left off.

Structural typing — no hard import on shaka-player

The ShakaAdapter constructor accepts any object that satisfies the ShakaPlayerLike interface exported from the package. The real shaka.Player satisfies this interface, but you can also pass a compatible mock in tests without importing the full Shaka library.

Cleanup

// When the player is torn down:
sdk.destroy(); // also destroys the internal ad player
await player.destroy();

THEOplayer Adapter

The official THEOplayer adapter is available as a separate package. Unlike HLS.js and Shaka, THEOplayer manages its own internal <video> element — you pass it a <div> container and it renders into that.

Install

npm install @dolby-optiview/ads-sdk-adapter-theoplayer theoplayer

Requirements

• THEOplayer v9 or later (peer dependency)
• A valid THEOplayer license key (passed in the player configuration)
• Set libraryLocation to serve THEOplayer's worker/WASM files — use a CDN or copy from node_modules/theoplayer/

Key difference — no raw <video> element

THEOplayer creates and manages its own <video> element inside the container div. The adapter exposes it via the videoElement getter (container.querySelector('video')) for GAM integration.

Full setup example

import { ChromelessPlayer } from 'theoplayer/chromeless';
import { OptiViewAds } from '@dolby-optiview/ads-sdk-core';
import { defaultAdAdapter } from '@dolby-optiview/ads-sdk';
import { THEOplayerAdapter } from '@dolby-optiview/ads-sdk-adapter-theoplayer';

const LICENSE = 'YOUR_THEOPLAYER_LICENSE';
const LIB = 'https://cdn.jsdelivr.net/npm/theoplayer@11.4.0/';

// 1. Content player — THEOplayer mounts into a <div>
const playerDiv = document.getElementById('player') as HTMLElement;
const player = new ChromelessPlayer(playerDiv, {
  license: LICENSE,
  libraryLocation: LIB,
  allowMixedContent: true,
  mutedAutoplay: 'all',
});
// 2. SDK — playerContainer is optional; SDK auto-wraps when omitted
const sdk = new OptiViewAds({
  player: new THEOplayerAdapter(player, playerDiv),
  container: document.getElementById('container'),
  createAdAdapter: (adContainer, sharedVideo) => {
    // Shared-element breaks (Safari picture-in-picture, OS-native fullscreen) hand over the
    // content <video>; a ChromelessPlayer cannot adopt an existing element, so let the SDK's
    // own engine play there.
    if (sharedVideo) return defaultAdAdapter(adContainer, sharedVideo);
    const adPlayer = new ChromelessPlayer(adContainer, {
      license: LICENSE,
      libraryLocation: LIB,
      allowMixedContent: true,
      mutedAutoplay: 'all',
    });
    return new THEOplayerAdapter(adPlayer, adContainer);
  },
});

// 3. Start session and load stream
await sdk.startSession({
  manifestUrl: 'https://manifest.example.com/v1/your-org/channels/your-channel',
});
player.source = { sources: [{ src: 'https://example.com/live.m3u8' }] };
player.play();

defaultAdAdapter is exported by @dolby-optiview/ads-sdk.

Picture-in-picture on Safari

Safari does not let the SDK move a picture-in-picture window to a second <video>, so a break that starts in PiP plays the ad through the content player's own element and hands it back to THEOplayer afterwards. Two things are required for the window to survive the break:

• createAdAdapter must honour the sharedVideo argument as shown above. A ChromelessPlayer created for the handed-over element fails inside THEOplayer's IMA module (AdError 1101) and the break never starts.
• A THEOplayer build that keeps the media element's resource attached across a source change while the element is in PiP. THEOplayer Web SDK 11.12.1 and earlier empty the element on every source change, and WebKit closes the window the moment an element has no media resource — the SDK cannot prevent that from outside the player. A player-side change is in progress with the THEOplayer team.

Expect one blank frame when content resumes: the browser resets the decoder when THEOplayer attaches the content MediaSource over the ad's. Setting preload: 'auto' (or 'metadata') on the content player shortens the gap.

Autoplay configuration

The ad player's play() is triggered by the SDK's break scheduler — always outside a user gesture. Set mutedAutoplay: 'all' in the ChromelessPlayer config for both the content and ad player instances. This tells THEOplayer to permit autoplay regardless of browser policy.

PDT (Program Date Time)

The THEOplayer adapter reads player.currentProgramDateTime directly — THEOplayer exposes the wall-clock position as a Date on that property for live HLS/DASH streams. No custom manifest parsing is needed.

Cleanup

sdk.destroy(); // also destroys the internal ad player
player.destroy();

Native / Safari & iOS (NativeVideoAdapter)

@dolby-optiview/ads-sdk ships a NativeVideoAdapter backed by a plain HTMLVideoElement. The default ad player (a RoutingAdAdapter) chooses its playback technology from the ad creative, not from Hls.isSupported() alone — so it uses NativeVideoAdapter in two cases:

• a progressive STATIC creative (MP4/WebM/…) — routed to native <video> even on MSE browsers where HLS.js is available, because HLS.js can only parse HLS playlists (feeding it an MP4 fails with manifestParsingError);
• any creative on platforms without a Media Source engine (Hls.isSupported() === false), notably iPhone/iPod on iOS < 17.1 and older iOS/tvOS WebViews, which play HLS natively via video.src.

An HLS playlist creative (.m3u8 / application/vnd.apple.mpegurl) goes through the HlsJsAdapter when HLS.js is supported. The technology is decided at load() time from the URL extension, with a Content-Type HEAD probe for extensionless URLs (e.g. GAM pod manifests, which stay on HLS.js); anything that can't be classified defaults to HLS.js.

iOS 17.1+ uses HLS.js for HLS creatives. Apple's Managed Media Source (MMS) is available on iPhone from iOS 17.1, so Hls.isSupported() returns true and HLS playlist creatives play through the HlsJsAdapter (full ABR, quality/track selection, precise buffering); progressive MP4 creatives still use NativeVideoAdapter. On older iOS and other MSE-less runtimes everything falls back to NativeVideoAdapter.

// Inside @dolby-optiview/ads-sdk's default ad adapter, per creative at load() time:
// The Content-Type probe is bounded at 5s; a host that never answers falls back to 'hls'.
const tech = selectAdTech(url); // 'native' | 'hls' (extension, then Content-Type)
if (tech === 'hls' && Hls.isSupported()) {
  // → HlsJsAdapter (MSE) for HLS playlists
} else {
  // → NativeVideoAdapter (progressive MP4/WebM, or native HLS fallback)
}

You normally never construct it directly — use @dolby-optiview/ads-sdk and it is selected for you. Import it explicitly only if you build a custom factory:

import { NativeVideoAdapter } from '@dolby-optiview/ads-sdk';

Demo content player (PLAYG-36). The same NativeVideoAdapter also backs the demo's "Native HLS" content player option. The demo auto-selects it for the content <video> whenever Hls.isSupported() is false (the MSE-less tail: iPhone Safari < 17.1, older iOS/tvOS WebViews) so content still plays via video.src; on MSE/MMS-capable runtimes hls.js stays the default. You can also force it via the ?player=native URL param to exercise the native path on an MSE-capable browser such as macOS Safari.

PDT (Program Date Time)

Wallclock break matching is supported on native HLS: NativeVideoAdapter derives programDateTime from WebKit's non-standard HTMLVideoElement.getStartDate() (the presentation origin's wallclock) plus currentTime, mirroring how the HLS.js adapter computes it. It returns null only on engines without getStartDate() or when the date is invalid — in which case wallclock matching is unavailable for that stream.

iPhone / iPod: adaptive & shared-element insertion

On iPhone/iPod, adInsertion: 'auto' (the default) resolves based on Managed Media Source availability:

• iOS 17.1+ (MMS present) → adaptive. Playback runs through HLS.js/MMS, so the SDK uses the full overlay compositor (all break formats) while the content video is inline, and falls back to a single fullscreen shared-element ad only while the content video is in OS-native fullscreen (where DOM overlays cannot render). The mode is re-evaluated per break from the content video's webkitDisplayingFullscreen state / webkitbeginfullscreen/webkitendfullscreen events.
• iOS < 17.1 (no MMS) → shared-element. The ad plays through the content <video> rather than a separate ad element; advanced formats are downgraded to a single fullscreen ad and lshape_content is skipped.

See SDK Configuration → Ad insertion behaviour.

AirPlay note: MMS sets disableRemotePlayback=true, disabling AirPlay on the SDK-owned ad element (ads are not AirPlayed). If you need AirPlay on your content player, append an HLS <source> element to your own content <video>.

Implementing a Custom Adapter

To use the SDK with Video.js, AVPlayer (iOS), or any other HLS-capable player, implement the PlayerAdapter interface.

TypeScript skeleton

import type {
  PlayerAdapter,
  PlayerAdapterEvent,
  PlayerAdapterEventHandler,
} from '@dolby-optiview/ads-sdk-core';

export class MyPlayerAdapter implements PlayerAdapter {
  private player: MyPlayer; // ← your player instance
  private video: HTMLVideoElement;
  private listeners = new Map<PlayerAdapterEvent, Set<PlayerAdapterEventHandler>>();
  private _programDateTime: Date | null = null;

  constructor(player: MyPlayer, videoElement: HTMLVideoElement) {
    this.player = player;
    this.video = videoElement;
    this.setupListeners();
  }

  // ── Required properties ──────────────────

  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(v) {
    this.video.muted = v;
  }
  get volume() {
    return this.video.volume;
  }
  set volume(v) {
    this.video.volume = v;
  }

  get programDateTime(): Date | null {
    // Track EXT-X-PROGRAM-DATE-TIME from your player's manifest events
    return this._programDateTime;
  }

  // ── Required methods ─────────────────────

  pause(): void {
    this.video.pause();
  }

  async play(): Promise<void> {
    await this.video.play();
  }

  seek(time: number): void {
    this.video.currentTime = time; // adapt to your player's seek API if needed
  }

  /** Load URL — resolve when manifest is parsed and player is ready to play. */
  async load(url: string): Promise<void> {
    return new Promise((resolve, reject) => {
      this.player.once('manifestparsed', resolve); // adapt to your player's event
      this.player.once('error', reject);
      this.player.load(url);
    });
  }

  on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void {
    if (!this.listeners.has(event)) this.listeners.set(event, new Set());
    this.listeners.get(event)!.add(handler);
  }

  off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler): void {
    this.listeners.get(event)?.delete(handler);
  }

  destroy(): void {
    this.listeners.clear();
    // Remove any event listeners added in setupListeners()
  }

  // ── Internal helpers ─────────────────────

  private emit(event: PlayerAdapterEvent, data?: unknown): void {
    this.listeners.get(event)?.forEach((h) => h(data));
  }

  private setupListeners(): void {
    // Forward native video events to SDK listeners
    this.video.addEventListener('timeupdate', () => this.emit('timeupdate'));
    this.video.addEventListener('ended', () => this.emit('ended'));
    this.video.addEventListener('error', () => this.emit('error'));
    this.video.addEventListener('seeked', () => this.emit('seeked'));
    this.video.addEventListener('volumechange', () => this.emit('volumechange'));

    // Track PDT from your player's manifest events
    this.player.on('fragmentchanged', (frag) => {
      if (frag.programDateTime) this._programDateTime = new Date(frag.programDateTime);
    });
  }
}

Validate your adapter

@dolby-optiview/ads-sdk-adapter-test-kit provides a shared conformance suite so you can prove your adapter satisfies the contract the SDK relies on (event forwarding, state mirroring, seek, destroy cleanup, and optional capabilities). The official HLS.js and Shaka adapters run the same kit.

# not on npmjs: install the tarball from the artefact host (see Install → Web)
npm install -D <artefact host>/web/<channel>/<version>/dolby-ads-adapter-test-kit-<version>.tgz

// MyPlayerAdapter.conformance.test.ts
import { runAdapterConformance } from '@dolby-optiview/ads-sdk-adapter-test-kit';
import { MyPlayerAdapter } from './MyPlayerAdapter';

runAdapterConformance('MyPlayerAdapter', {
  // Construct your adapter around the kit-provided <video> element.
  createAdapter: (video) => new MyPlayerAdapter(createMyPlayer(), video),
  // Declare which optional members you implement so the matching checks run.
  capabilities: { videoElement: true, preload: false, parallelBuffering: false },
});

The kit registers its own describe/it blocks, so just call runAdapterConformance(...) at the top level of a test file. By default it makes the underlying source emit each event by dispatching a native Event on the video element; pass a custom emit(video, event) if your player surfaces events differently.

Getting Started

Requirements

• Android minSdk 21 (Android TV supported), compileSdk 34
• Media3 / ExoPlayer 1.4.x
• For Google Ad Manager pod serving: the IMA SDK (com.google.ads.interactivemedia.v3:interactivemedia)

Installation

Stable releases use the public THEOplayer Maven repository. Add it to settings.gradle.kts, retaining Google and Maven Central for third-party libraries:

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://maven.theoplayer.com/releases") }
        google()
        mavenCentral()
    }
}

For a beta or other tagged prerelease, also add maven { url = uri("https://maven.theoplayer.com/snapshots") } and pin the exact version, such as 1.0.0-beta.1. Keep /releases for stable dependencies; do not use snapshotsOnly(), because prerelease versions retain their original suffix. Develop/custom builds still use the artifact-host flow in Install / Distribution. The app also needs JDK 17 and android.useAndroidX=true.

// build.gradle.kts (app module) — published coordinates
dependencies {
    implementation("com.dolby.optiview:ads-sdk-runtime:<version>")  // ExoPlayerAdapter + OverlayAdRenderer + GAM/IMA
    // ads-sdk-runtime re-exports the core + sdk layers transitively.

    implementation("androidx.media3:media3-exoplayer:1.4.1")
    implementation("androidx.media3:media3-ui:1.4.1")
}

Quick start

import androidx.media3.common.MediaItem
import androidx.media3.exoplayer.ExoPlayer
import androidx.media3.ui.PlayerView
import com.dolby.optiview.ads.runtime.ExoPlayerAdapter
import com.dolby.optiview.ads.runtime.OverlayAdRenderer
import com.dolby.optiview.ads.sdk.CoroutineSchedulerTicker
import com.dolby.optiview.ads.sdk.OptiViewAds
import com.dolby.optiview.ads.sdk.OptiViewAdsConfig
import com.dolby.optiview.ads.sdk.OptiViewAdsEventType
import com.dolby.optiview.ads.sdk.HttpManifestSource
import com.dolby.optiview.ads.sdk.SessionConfig
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch

val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)

// 1. Content player — you own the ExoPlayer and attach it to your PlayerView.
val contentPlayer = ExoPlayer.Builder(context).build()
playerView.player = contentPlayer
val contentAdapter = ExoPlayerAdapter(contentPlayer)

// 2. Runtime seams: overlay ad renderer + HTTP manifest source + coroutine ticker.
//    `overlayContainer` is a FrameLayout stacked above your PlayerView.
val renderer       = OverlayAdRenderer(context, overlayContainer, contentAdapter)
val manifestSource = HttpManifestSource(scope)
val ticker         = CoroutineSchedulerTicker(scope)

// 3. Create the SDK.
val sdk = OptiViewAds(
    config = OptiViewAdsConfig(player = contentAdapter, debug = true),
    renderer = renderer,
    manifestSource = manifestSource,
    ticker = ticker,
    scope = scope,
)

// 4. Listen to events.
sdk.addEventListener(OptiViewAdsEventType.ADBREAKBEGIN) { e -> Log.d("Ads", "Break started: ${e.breakId}") }
sdk.addEventListener(OptiViewAdsEventType.ADBREAKEND)   { e -> Log.d("Ads", "Break ended: ${e.breakId}") }
sdk.addEventListener(OptiViewAdsEventType.ADCHANNELCHANGE) { e ->
    Log.d("Ads", "Channel changed: ${e.previousChannelId} -> ${e.channelId} (${e.previousDeliveryMode} -> ${e.deliveryMode})")
}

// 5. Load your content stream and start a monetization session.
contentPlayer.setMediaItem(MediaItem.fromUri("https://example.com/live.m3u8"))
contentPlayer.prepare()
contentPlayer.playWhenReady = true

scope.launch {
    sdk.startSession(SessionConfig(manifestUrl = "https://manifest.example.com/v1/your-org/channels/your-channel"))
}

During an active ad break, the event is emitted after that break finishes and the latest polled manifest is applied.

Every published Android SDK version uses the same embedded manifest trust list: ads-prod-2026-08, ads-staging-2026-08, and ads-dev-2026-08. HttpManifestSource(scope) accepts an optional ManifestFetcher for transport integration, but its public constructor cannot accept custom trusted keys. The repository test key is available only to unit/conformance tests through an internal testability seam; CI does not select Android keys by branch or version.

Ad formats & overlay rendering

Native ad creatives default to AdScaling.FIT (aspect-fit/contain), matching the web renderer's primary ad surfaces. Pass adScaling = AdScaling.FILL to opt into aspect-fill cropping. Companion/backdrop artwork remains cover-scaled independently, and fullscreen ad surfaces follow the visible content picture rectangle when the adapter reports intrinsic video dimensions.

OverlayAdRenderer renders every break format. For the overlay format it positions/sizes the ad surface from the manifest position/size/opacity and does not pause the content player (the ad plays on top of playing content); all other formats render full-surface and pause content. Overlay assets with mediaType: "image" are rendered in a ImageView (held for the asset's duration, falling back to the break duration), are preloaded for an instant transition, and on load failure dispatch aderror and are ignored — identical to the web and iOS runtimes. See Ad Formats.

SGAI GAM and VAST controls share the ad video's visibility and disappear when its presentation ends, including after errors or a forced break cutoff. No application-side IMA view cleanup is required. Stitched SSAI controls remain separate from the SDK's ad video surface.

Reading the SDK version

Read the current SDK version from the static OptiViewAds.version accessor — no instance required. It is the same lockstep version as the web and iOS SDKs and the stitcher's GET /version.

import com.dolby.optiview.ads.sdk.OptiViewAds

Log.d("Ads", OptiViewAds.version) // e.g. "0.16.0"

Google Ad Manager (pod serving)

Supply a GamConfig to the renderer and to OptiViewAdsConfig. Its presence is the opt-in — the stream identity comes from the break manifest's vendorConfiguration. GAM vendor breaks are served via Google IMA DAI.

import com.dolby.optiview.ads.sdk.GamConfig

val gam = GamConfig()
val renderer = OverlayAdRenderer(context, overlayContainer, contentAdapter, gamConfig = gam)

val sdk = OptiViewAds(
    config = OptiViewAdsConfig(player = contentAdapter, gam = gam),
    renderer = renderer,
    manifestSource = manifestSource,
    ticker = ticker,
    scope = scope,
)

scope.launch {
    sdk.startSession(SessionConfig(manifestUrl = "https://manifest.example.com/v1/your-org/channels/your-channel"))
}

Break transitions (transition)

How the picture changes at the edges of a break. The ad surface is held back until the ad has actually rendered its first frame, then cross-fades in over the paused content frame; at the end it dissolves away over resumed content. Nothing is shown while it is still blank, which is what removes the black flash at a fullscreen (single) break.

OptiViewAdsConfig(
    player = contentAdapter,
    transition = TransitionConfig(),                              // fade, 300ms (default)
    // transition = TransitionConfig(type = TransitionType.NONE), // cut, no animation
    // transition = TransitionConfig(durationMs = 500),           // slower fade
)

An ad that renders no frame at all — an audio-only creative, or a decoder that never answers — is revealed anyway once the ad-start deadline passes, so it can never play invisibly. Every reveal emits DA-AD-SURFACE-REVEALED with reason (first-frame vs reveal-timeout) and waitedMs, the wait that would otherwise have been a black gap.

For a format that covers content (single, lshape_ad), content keeps playing under the fade and is paused as it lands, so the ad dissolves over moving video rather than over a still frame. Its audio is muted from the start of the break (and restored at the end, preserving a viewer's own mute), because two pictures may overlap during a cross-fade but two soundtracks may not. Under adPreload = single-decoder the pause stays immediate: that mode exists to avoid holding two decoders, which is exactly what playing content through the ad's load would do. Either way the content resume at break end is unchanged.

Existing Adapter — ExoPlayerAdapter

The runtime ships ExoPlayerAdapter, a Media3/ExoPlayer implementation of PlayerAdapter. It wraps an ExoPlayer instance you create and own (attached to your own PlayerView); the SDK drives the content player only through this adapter, keeping the brain player-agnostic.

import com.dolby.optiview.ads.runtime.ExoPlayerAdapter

val contentPlayer = ExoPlayer.Builder(context).build()
val contentAdapter = ExoPlayerAdapter(contentPlayer)
// → pass as OptiViewAdsConfig.player (and to OverlayAdRenderer).

THEOplayer Adapter — THEOplayerAdapter

The ads-sdk-adapter-theoplayer artifact wraps a com.theoplayer.android.api.player.Player. THEOplayer is compileOnly in the adapter, so the host app provides its own com.theoplayer.theoplayer-sdk-android:core dependency.

// app/build.gradle.kts
implementation("com.dolby.optiview:ads-sdk-adapter-theoplayer:<version>")
implementation("com.theoplayer.theoplayer-sdk-android:core:<version>")

import com.dolby.optiview.ads.adapter.theoplayer.THEOplayerAdapter
import com.theoplayer.android.api.player.Player

val contentAdapter = THEOplayerAdapter(player)

PlayerAdapter Interface

Any content player is integrated by implementing PlayerAdapter from com.dolby.optiview.ads.core. Unlike the web adapter (whose load/play return Promises), the Kotlin load/play are synchronous — they kick off preparation/playback and return immediately; readiness and completion are signalled via PlayerAdapterEvents.

package com.dolby.optiview.ads.core

/** Event types a PlayerAdapter must forward. */
enum class PlayerAdapterEvent(val value: String) {
    TIMEUPDATE("timeupdate"),
    ENDED("ended"),
    ERROR("error"),
    SEEKED("seeked"),
    VOLUMECHANGE("volumechange"),
    WAITING("waiting"),
    PLAYING("playing"),
}

/** Handler payload carries adapter-specific detail (e.g. a media error). */
typealias PlayerAdapterEventHandler = (event: Any?) -> Unit

interface PlayerAdapter {
    /** Current playback time in seconds. */
    val currentTime: Double

    /** Total content duration in seconds; Double.POSITIVE_INFINITY for live. */
    val duration: Double

    /** Whether the player is currently paused. */
    val paused: Boolean

    /** Muted state. Settable so the SDK can sync content↔ad mute. */
    var muted: Boolean

    /** Volume in [0, 1]. Settable so the SDK can sync content↔ad volume. */
    var volume: Double

    /** Program Date Time (EXT-X-PROGRAM-DATE-TIME) as epoch milliseconds,
     *  for wallclock-timebase break matching. Null when unavailable. */
    val programDateTime: Long?

    /** Pause playback (called when an ad break starts). */
    fun pause()

    /** Resume playback (called when an ad break ends). Returns immediately. */
    fun play()

    /** Seek to time seconds (used for snapback during locked breaks). */
    fun seek(time: Double)
    fun seekExact(time: Double) // SDK-owned post-break resume positioning

    /** Load a media source without committing to immediate playback. */
    fun load(url: String)

    /** Optional: warm caches WITHOUT engaging a decoder (single-decoder preload). */
    fun preload(url: String) {}

    /** Optional capability hint: can this adapter buffer a second source in
     *  parallel without decoder contention? Null is treated as true. */
    val supportsParallelBuffering: Boolean?
        get() = null

    /** Subscribe to a player event. */
    fun on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

    /** Unsubscribe a previously registered handler. */
    fun off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler)

    /** Clean up resources (called when the SDK is destroyed). */
    fun destroy()
}

Implementing a Custom Adapter

To use the SDK with a different player, implement PlayerAdapter and forward your player's callbacks to the SDK event handlers.

import com.dolby.optiview.ads.core.PlayerAdapter
import com.dolby.optiview.ads.core.PlayerAdapterEvent
import com.dolby.optiview.ads.core.PlayerAdapterEventHandler

class MyPlayerAdapter(private val player: MyPlayer) : PlayerAdapter {

    private val handlers = mutableMapOf<PlayerAdapterEvent, MutableSet<PlayerAdapterEventHandler>>()

    init {
        // Forward your player's callbacks to the SDK.
        player.onPositionChanged { dispatch(PlayerAdapterEvent.TIMEUPDATE) }
        player.onEnded          { dispatch(PlayerAdapterEvent.ENDED) }
        player.onError          { err -> dispatch(PlayerAdapterEvent.ERROR, err) }
        player.onSeeked         { dispatch(PlayerAdapterEvent.SEEKED) }
        player.onVolumeChanged  { dispatch(PlayerAdapterEvent.VOLUMECHANGE) }
    }

    // ── Required properties ──────────────────
    override val currentTime: Double get() = player.positionMs / 1000.0
    override val duration: Double get() = if (player.isLive) Double.POSITIVE_INFINITY else player.durationMs / 1000.0
    override val paused: Boolean get() = !player.isPlaying

    override var muted: Boolean
        get() = player.volume == 0f
        set(value) { player.volume = if (value) 0f else 1f }

    override var volume: Double
        get() = player.volume.toDouble()
        set(value) { player.volume = value.coerceIn(0.0, 1.0).toFloat() }

    override val programDateTime: Long?
        get() = player.currentProgramDateEpochMs   // null for VOD / no PDT

    // ── Required methods ─────────────────────
    override fun pause() = player.pause()
    override fun play()  = player.play()
    override fun seek(time: Double) { player.seekTo((time * 1000).toLong()) }
    override fun load(url: String)  { player.setSource(url); player.prepare() }

    override fun on(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler) {
        handlers.getOrPut(event) { mutableSetOf() }.add(handler)
    }

    override fun off(event: PlayerAdapterEvent, handler: PlayerAdapterEventHandler) {
        handlers[event]?.remove(handler)
    }

    override fun destroy() {
        handlers.clear()
        // Remove any listeners registered on `player`.
    }

    private fun dispatch(event: PlayerAdapterEvent, payload: Any? = null) {
        handlers[event]?.toList()?.forEach { it(payload) }
    }
}

Validate your adapter

Add the conformance kit to the test source set:

testImplementation("com.dolby.optiview:ads-sdk-adapter-test-kit:<version>")

Extend PlayerAdapterConformanceTest and override createAdapter():

import com.dolby.optiview.ads.core.PlayerAdapter
import com.dolby.optiview.ads.testkit.PlayerAdapterConformanceTest

class MyPlayerAdapterTest : PlayerAdapterConformanceTest() {
    override fun createAdapter(): PlayerAdapter = MyPlayerAdapter(player)
}

Getting Started

Requirements

• iOS / tvOS 15+ (the runtime depends on the Google IMA SDK, which requires 15+)
• AVFoundation / AVPlayer
• For Google Ad Manager pod serving: GoogleInteractiveMediaAds — Google ships it as two platform-specific SPM packages exporting the same module (…-google-interactive-media-ads-ios for iOS, …-google-interactive-media-ads-tvos for tvOS); add the one(s) matching your app's platforms

Installation

The xcframeworks are published per release; take each url and checksum from that release's manifest.json — see Install / Distribution.

// Package.swift — Swift Package Manager
dependencies: [
    .package(url: "https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios", from: "3.18.4"),
    .package(url: "https://github.com/googleads/swift-package-manager-google-interactive-media-ads-tvos", from: "4.2.0"),
],
targets: [
    .binaryTarget(name: "OptiViewAdsCore",
        url: "<release base URL>/OptiViewAdsCore.xcframework.zip",
        checksum: "<see manifest.json>"),
    .binaryTarget(name: "OptiViewAdsSDK",
        url: "<release base URL>/OptiViewAdsSDK.xcframework.zip",
        checksum: "<see manifest.json>"),
    .binaryTarget(name: "OptiViewAdsRuntime",
        url: "<release base URL>/OptiViewAdsRuntime.xcframework.zip",
        checksum: "<see manifest.json>"),
    .target(name: "MyApp", dependencies: [
        "OptiViewAdsRuntime", "OptiViewAdsSDK", "OptiViewAdsCore",
        .product(name: "GoogleInteractiveMediaAds", package: "swift-package-manager-google-interactive-media-ads-ios",
                 condition: .when(platforms: [.iOS])),
        .product(name: "GoogleInteractiveMediaAdsTvOS", package: "swift-package-manager-google-interactive-media-ads-tvos",
                 condition: .when(platforms: [.tvOS])),
    ]),
]

# Podfile — CocoaPods
source 'https://github.com/THEOplayer/cocoapods-specs.git'
source 'https://cdn.cocoapods.org/'

pod 'OptiViewAdsRuntime', '<version>'

Quick start

import AVFoundation
import OptiViewAdsRuntime   // re-exports OptiViewAdsCore + OptiViewAdsSDK

// 1. Content player — you own the AVPlayer and render it (AVPlayerLayer / AVPlayerViewController).
let contentPlayer = AVPlayer()
playerLayer.player = contentPlayer
let contentAdapter = AVPlayerAdapter(player: contentPlayer)

// 2. Runtime seams: overlay ad renderer + Foundation manifest source + dispatch ticker.
//    `overlayContainer` is a UIView stacked above your content surface.
let renderer = OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter)

// 3. Create the SDK.
let sdk = OptiViewAds(
    config: OptiViewAdsConfig(player: contentAdapter, debug: true),
    renderer: renderer,
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

// 4. Listen to events (addEventListener returns a token for removeEventListener).
sdk.addEventListener(.adbreakbegin) { event in print("Break started:", event.breakId ?? "") }
sdk.addEventListener(.adbreakend)   { event in print("Break ended:", event.breakId ?? "") }

// 5. Load your content stream and start a monetization session.
if let url = URL(string: "https://example.com/live.m3u8") {
    contentPlayer.replaceCurrentItem(with: AVPlayerItem(url: url))
    contentPlayer.play()
}

Task {
    do {
        try await sdk.startSession(SessionConfig(manifestUrl: "https://manifest.example.com/v1/your-org/channels/your-channel"))
    } catch {
        print("startSession failed:", error)
    }
}

Every published iOS/tvOS SDK version uses the same embedded manifest trust list: ads-prod-2026-08, ads-staging-2026-08, and ads-dev-2026-08. URLSessionManifestSource(session:) accepts an optional URLSession for transport integration, but its public initializer cannot accept custom trusted keys. The repository test key is available only to unit/conformance tests through an internal testability seam; neither DEBUG builds nor CI change the Apple key list.

Ad formats & overlay rendering

Native ad creatives default to .fit (aspect-fit/contain), matching the web renderer's primary ad surfaces. Pass adScaling: .fill to opt into aspect-fill cropping. Companion/backdrop artwork remains cover-scaled independently, and fullscreen ad surfaces follow stageRect when the content picture geometry is available.

OverlayAdRenderer renders every break format. For the overlay format it positions/sizes the ad surface from the manifest position/size/opacity and does not pause the content player (the ad plays on top of playing content); all other formats render full-surface and pause content. Overlay assets with mediaType: "image" are rendered in a UIImageView (held for the asset's duration, falling back to the break duration), are preloaded for an instant transition, and on load failure dispatch aderror and are ignored — identical to the web and Android runtimes. See Ad Formats.

Reading the SDK version

Read the current SDK version from the static OptiViewAds.version property — no instance required. It is the same lockstep version as the web and Android SDKs and the stitcher's GET /version.

print(OptiViewAds.version) // e.g. "0.16.0"

Google Ad Manager (pod serving)

Supply a GamConfig to the renderer and to OptiViewAdsConfig. Its presence is the opt-in — the stream identity comes from the break manifest's vendorConfiguration. GAM vendor breaks are served via Google IMA DAI.

let gam = GamConfig()
let renderer = OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter, gamConfig: gam)

let sdk = OptiViewAds(
    config: OptiViewAdsConfig(player: contentAdapter, gam: gam),
    renderer: renderer,
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

Task {
    try await sdk.startSession(SessionConfig(manifestUrl: "https://manifest.example.com/v1/your-org/channels/your-channel"))
}

Break transitions (transition)

How the picture changes at the edges of a break — the same option (and defaults) as on Android. The ad surface is held back until the ad has actually rendered its first frame (AVPlayerLayer.isReadyForDisplay), then cross-fades in over the content; at the end it dissolves away over resumed content. Nothing is shown while it is still blank, which is what removes the black flash at a fullscreen (single) break.

OptiViewAdsConfig(
    player: contentAdapter,
    transition: TransitionConfig()                          // fade, 300ms (default)
    // transition: TransitionConfig(type: .none)            // cut, no animation
    // transition: TransitionConfig(durationMs: 500)        // slower fade
)

An ad that renders no frame at all — an audio-only creative, or a decoder that never answers — is revealed anyway once the ad-start deadline passes, so it can never play invisibly. Every reveal emits DA-AD-SURFACE-REVEALED with reason (first-frame vs reveal-timeout) and waitedMs, the wait that would otherwise have been a black gap.

For a format that covers content (single, lshape_ad), content keeps playing under the fade and is paused as it lands, so the ad dissolves over moving video rather than over a still frame. Its audio is muted from the start of the break (and restored at the end, preserving a viewer's own mute), because two pictures may overlap during a cross-fade but two soundtracks may not.

Picture-in-picture

The SDK owns picture-in-picture because the break format depends on it: while the window is open every break plays as single and the ad plays through the content player, since the window presents that player's surface and nothing else. Drive it with OptiViewAds.setPictureInPicture(_:); viewer-driven transitions (dismissing the window from the system UI) are detected and adopted automatically.

How the window is driven depends on the content adapter:

• AVPlayerAdapter — the SDK discovers the AVPlayerLayer presenting your content and runs its own AVPictureInPictureController against it. Nothing to configure beyond the platform requirements below.
• THEOplayer (or any adapter conforming to PictureInPictureCapable) — the window is driven through the player's own PiP facility (presentationMode), never an external controller: THEOplayer replaces its internal player/layer on a source change, which is exactly what happens when the ad borrows the content player, and an external controller's window dies at that moment. For the window to survive the ad hand-over you must construct the player with source-change retention — the SDK cannot set this after construction:

let pipConfig = PiPConfiguration(retainPresentationModeOnSourceChange: true)
let theoplayer = THEOplayer(configuration: THEOplayerConfiguration(pip: pipConfig, /* … */))

If you implement PictureInPictureCapable on your own adapter, note the change-handler contract: onPictureInPictureChange(_:) must also invoke the handler once with the current state at install time. The player outlives SDK sessions, so a window opened between sessions would otherwise go unreported and the next session would run breaks as if the window were closed. (The SDK also re-reads the state ~1s after every request it issues and diagnoses the outcome — DA-PIP-TRANSFER-FAILED when the player quietly refused.)

The renderer also reconciles the current PiP state at break setup and when ad media becomes ready, so a deferred adoption does not require a second enter notification. DA-PIP-ADOPTION-STATE explains deferred or already-applied decisions. On return from a shared-player VOD ad, the SDK marks the content reload as its own resume operation before resetting the source, preventing that backward jump from replaying the break.

Existing Adapter — AVPlayerAdapter

The runtime ships AVPlayerAdapter, an AVFoundation implementation of PlayerAdapter. It wraps an AVPlayer you create and own (rendered in your own layer / AVPlayerViewController); the SDK drives the content player only through this adapter, keeping the brain player-agnostic.

import OptiViewAdsRuntime

let contentPlayer = AVPlayer()
let contentAdapter = AVPlayerAdapter(player: contentPlayer)
// → pass as OptiViewAdsConfig.player (and to OverlayAdRenderer).

THEOplayer Adapter — THEOplayerAdapter

The OptiViewAdsAdapterTHEOplayer product wraps the native THEOplayer player. With SwiftPM, add the OptiViewAdsAdapterTHEOplayer and OptiViewAdsCore xcframeworks as binary targets, plus theoplayer-sdk-apple from 11.0.0. The binary target does not declare THEOplayer, so add theoplayer-sdk-apple yourself and make the app target depend on its THEOplayerSDK product. The OptiViewAdsAdapterTHEOplayer CocoaPod pulls THEOplayerSDK-core (~> 11.0).

// Package.swift — THEOplayer binary target and app-target dependencies
dependencies: [
    .package(url: "https://github.com/THEOplayer/theoplayer-sdk-apple", from: "11.0.0"),
],
targets: [
    .binaryTarget(name: "OptiViewAdsCore",
        url: "<release base URL>/OptiViewAdsCore.xcframework.zip",
        checksum: "<see manifest.json>"),
    .binaryTarget(name: "OptiViewAdsAdapterTHEOplayer",
        url: "<release base URL>/OptiViewAdsAdapterTHEOplayer.xcframework.zip",
        checksum: "<see manifest.json>"),
    .target(name: "MyApp", dependencies: [
        "OptiViewAdsAdapterTHEOplayer", "OptiViewAdsCore",
        .product(name: "THEOplayerSDK", package: "theoplayer-sdk-apple"),
    ]),
]

import OptiViewAdsAdapterTHEOplayer

let contentAdapter = THEOplayerAdapter(player: theoplayer)

# Podfile — THEOplayer adapter
pod 'OptiViewAdsAdapterTHEOplayer', '<version>'

PlayerAdapter Protocol

Any content player is integrated by conforming to PlayerAdapter from OptiViewAdsCore. Subscriptions are tracked by an opaque PlayerEventToken (Swift closures are not identity-comparable), so on(_:_:) returns a token you pass to off(_:).

/// Event types a PlayerAdapter forwards.
public enum PlayerAdapterEvent: String {
    case timeupdate, ended, error, seeked, volumechange, waiting, playing
}

/// Handler payload carries adapter-specific detail (e.g. a media error).
public typealias PlayerAdapterEventHandler = (Any?) -> Void

/// Opaque token so a specific handler can later be removed via `off(_:)`.
public final class PlayerEventToken { public init() {} }

public protocol PlayerAdapter: AnyObject {
    /// Current playback time in seconds.
    var currentTime: Double { get }

    /// Total content duration in seconds; `.infinity` for live.
    var duration: Double { get }

    /// Whether the player is currently paused.
    var paused: Bool { get }

    /// Muted state. Settable so the SDK can sync content↔ad mute.
    var muted: Bool { get set }

    /// Volume in [0, 1]. Settable so the SDK can sync content↔ad volume.
    var volume: Double { get set }

    /// Program Date Time (EXT-X-PROGRAM-DATE-TIME) as epoch milliseconds,
    /// for wallclock-timebase break matching. Nil when unavailable.
    var programDateTime: Int64? { get }

    func pause()                  // called when an ad break starts
    func play()                   // called when an ad break ends
    func seek(_ time: Double)     // used for snapback during locked breaks
    func load(_ url: String)      // load without committing to immediate playback

    /// Optional: warm caches without engaging a decoder (single-decoder preload).
    func preload(_ url: String)

    /// Optional capability hint: can this adapter buffer a second source in
    /// parallel without decoder contention? Nil is treated as true.
    var supportsParallelBuffering: Bool? { get }

    /// Subscribe to a player event; returns a token for `off(_:)`.
    @discardableResult
    func on(_ event: PlayerAdapterEvent, _ handler: @escaping PlayerAdapterEventHandler) -> PlayerEventToken

    /// Unsubscribe a previously registered handler by its token.
    func off(_ token: PlayerEventToken)

    /// Clean up resources (called when the SDK is destroyed).
    func destroy()
}

// `preload` and `supportsParallelBuffering` have default implementations.
public extension PlayerAdapter {
    func preload(_ url: String) {}
    var supportsParallelBuffering: Bool? { nil }
}

Implementing a Custom Adapter

To use the SDK with a different player, conform to PlayerAdapter and forward your player's callbacks to the SDK event handlers.

import OptiViewAdsCore

final class MyPlayerAdapter: PlayerAdapter {

    private let player: MyPlayer
    private var handlers: [PlayerAdapterEvent: [ObjectIdentifier: PlayerAdapterEventHandler]] = [:]

    init(player: MyPlayer) {
        self.player = player
        // Forward your player's callbacks to the SDK.
        player.onPositionChanged = { [weak self] in self?.dispatch(.timeupdate) }
        player.onEnded           = { [weak self] in self?.dispatch(.ended) }
        player.onError           = { [weak self] err in self?.dispatch(.error, err) }
        player.onSeeked          = { [weak self] in self?.dispatch(.seeked) }
        player.onVolumeChanged   = { [weak self] in self?.dispatch(.volumechange) }
    }

    // ── Required properties ──────────────────
    var currentTime: Double { player.positionSeconds }
    var duration: Double { player.isLive ? .infinity : player.durationSeconds }
    var paused: Bool { !player.isPlaying }

    var muted: Bool {
        get { player.volume == 0 }
        set { player.volume = newValue ? 0 : 1 }
    }

    var volume: Double {
        get { Double(player.volume) }
        set { player.volume = Float(max(0, min(1, newValue))) }
    }

    var programDateTime: Int64? { player.currentProgramDateEpochMs }   // nil for VOD / no PDT

    // ── Required methods ─────────────────────
    func pause() { player.pause() }
    func play()  { player.play() }
    func seek(_ time: Double) { player.seek(toSeconds: time) }
    func load(_ url: String)  { if let u = URL(string: url) { player.setSource(u) } }

    @discardableResult
    func on(_ event: PlayerAdapterEvent, _ handler: @escaping PlayerAdapterEventHandler) -> PlayerEventToken {
        let token = PlayerEventToken()
        handlers[event, default: [:]][ObjectIdentifier(token)] = handler
        return token
    }

    func off(_ token: PlayerEventToken) {
        let key = ObjectIdentifier(token)
        for event in handlers.keys { handlers[event]?.removeValue(forKey: key) }
    }

    func destroy() {
        handlers.removeAll()
        // Remove any observers registered on `player`.
    }

    private func dispatch(_ event: PlayerAdapterEvent, _ payload: Any? = nil) {
        handlers[event]?.values.forEach { $0(payload) }
    }
}

Validate your adapter

With SwiftPM, declare the OptiViewAdsAdapterTestKit and OptiViewAdsCore binary targets and depend on both from the test target only. Use the OptiViewAdsAdapterTestKit URL and checksum from the release manifest.json.

targets: [
    .binaryTarget(name: "OptiViewAdsCore",
        url: "<release base URL>/OptiViewAdsCore.xcframework.zip",
        checksum: "<see manifest.json>"),
    .binaryTarget(name: "OptiViewAdsAdapterTestKit",
        url: "<release base URL>/OptiViewAdsAdapterTestKit.xcframework.zip",
        checksum: "<see manifest.json>"),
    .testTarget(name: "MyPlayerAdapterTests", dependencies: [
        "OptiViewAdsAdapterTestKit", "OptiViewAdsCore",
    ]),
]

import OptiViewAdsAdapterTestKit
import OptiViewAdsCore

final class MyPlayerAdapterTests: PlayerAdapterConformanceTestCase {
    override func makeAdapter() -> PlayerAdapter {
        MyPlayerAdapter(player: makePlayer())
    }
}

Override triggerVolumeChange(_:) -> Bool when the player can synthesize a volume-change event headlessly.

Web

OptiViewAdsConfig constructor

Ad preload behaviour (adPreload)

Controls how the next ad is prepared before a break starts.

In single-decoder mode, content paused for a full-screen ad stays paused until the ad media is released. Live pre-positioning and muted catch-up behind the ad are disabled on this path; the existing release grace precedes the content resume seek and play. The default native ad adapter resets its owned media pipeline rather than only removing src. Parallel-mode alignment is unchanged.

Content recovery after a break (adBreakContentRecovery)

Controls how the content player is brought back when an ad break ends. This is a web-only option: the Android, iOS and React Native bridges accept it and ignore it, because their native players resume in place without the rebuild.

Ad insertion behaviour (adInsertion)

Controls how the ad is composited relative to the content player.

Web shared-element content return

After a shared-element ad, restoring content has at most two attempts, each with a five-second deadline covering load, live-edge recovery and play. A timeout or repeated rejection reports DA-SHARED-ELEMENT-RESTORE-FAILED with its phase and reason. Starting another break, ending the session or destroying the SDK cancels old recovery work so late SDK continuations cannot restart the wrong content. These limits do not cancel an adapter's own in-flight work.

The existing five-second progress watchdog still reports DA-CONTENT-RESUME-STALLED when an applicable completed restore does not advance. It does not monitor later viewer pauses indefinitely. A post-roll triggered by content ending restores the ended source but does not resume it.

Consecutive-break chaining (chaining)

Some channels schedule two (or more) breaks back to back — for example two breaks with different ad targeting parameters separated by a ~1s gap. Without chaining, each break ends independently: content briefly resumes, the layout animates back to fullscreen, then the next break re-pauses content and re-applies its layout — a visible flash, often followed by a spinner while the next ad loads.

With chaining enabled (the default), breaks whose gap is ≤ maxGapSeconds are played as one continuous ad sequence:

• The ad overlay is held across the gap — content is never resumed and the layout is not torn down (no flash).
• The next break's first (static) asset is preloaded during the current break (HTTP cache warm + a detached prefetch), so it starts without a spinner. This never attaches a second MediaSource, so it is safe on single-decoder Smart TVs.
• Each break still emits its own adbreakbegin / adbreakend events and resolves its own targeting, so analytics and per-break ad requests are unchanged.

const sdk = new OptiViewAds({
  // ...
  chaining: { enabled: true, maxGapSeconds: 2 },
});

Tune-in / join-in-progress (tuneIn)

Live viewers rarely join exactly at a break boundary — they often tune in while an ad break is already playing. By default the SDK detects this and presents the break for the time that remains, rather than skipping it entirely (the legacy behaviour, which left the join-in-progress window unmonetised).

With tune-in enabled (the default), when the SDK first observes a break that has already started:

• If at least minBreakDurationSeconds of the break remain, the break is triggered for its remaining duration. The adbreakbegin event carries a tuneIn: { elapsedSec, remainingSec } payload, and the break-cut countdown allows that remaining duration plus the safety margin from actual ad playback. Startup does not consume the remainder; content may return after the original boundary.
• For GAM pod serving, the pod request is built for the remaining duration, so the ad server returns a pod that fits the time left.
• If less than minBreakDurationSeconds remain, the break is not triggered (no partial sliver of an ad is shown, and it is not monetised).

const sdk = new OptiViewAds({
  // ...
  tuneIn: { enabled: true, minBreakDurationSeconds: 5 },
});

SSAI mode (mode: 'ssai')

By default the SDK runs SGAI (client-scheduled) insertion, unless the break manifest's delivery rules steer the session to ssai (see Delivery steering on the Break Manifest page — manifest-steered ssai uses the gam vendor configuration's assetKey and needs no stitcherUrl). Set mode: 'ssai' explicitly to switch to the stitcher-based server-side ad insertion: the SDK plays a single pre-stitched stream from the @dolby-optiview/ads-sdk-stitcher service on the content player. It does not poll a break manifest, schedule breaks, or run an ad-player overlay. Instead it:

1. creates the IMA DAI stream (for a stream_id),
2. builds the stitcher master URL and loads it into the content player,
3. forwards in-stream timedmetadata cues to IMA for ad tracking, and
4. re-emits the usual ad-event stream (adbreakbegin / adbegin / quartiles / adend / adbreakend).

const sdk = new OptiViewAds({
  mode: 'ssai',
  player: new HlsJsAdapter(hls, video), // must expose videoElement (IMA binds to it)
  gam: {},
  ssai: { networkCode: '23285652104' }, // SSAI only: no break manifest to read it from
  maxBitrate: 2000000, // optional — caps rendition bitrate (max_bitrate on the master URL)
  autoplay: true, // optional — SDK plays the stitched stream after load
});

// The SDK loads the stitched master itself — do not load a content URL.
await sdk.startSession({
  stitcherUrl: 'https://stitch.example.com/ssai/v1/your-org/your-channel/master.m3u8',
  customAssetKey: 'asset-key',
});

Manifest interception (interceptManifestRequest / interceptManifestResponse)

Two optional SGAI hooks bracket the manifest fetch:

• interceptManifestRequest runs before the network call (initial fetch + every poll). Return a ManifestRequest to redirect the URL or add headers, a ManifestMockResponse to short-circuit the network with a raw body (parsed + validated normally), or nothing to fetch unchanged. A throw is non-fatal (DA-MANIFEST-REQUEST-INTERCEPT-FAILED, falls back to the network fetch). Primarily a testing aid (mock/redirect without a proxy).
• interceptManifestResponse runs after fetch + validation, handing you the parsed, validated BreakManifest so you can transform it — inject a pre-roll, drop a break, rewrite an asset URL — before it is scheduled. The return value is used as-is; a throw is non-fatal (DA-MANIFEST-INTERCEPT-FAILED, falls back to the unmodified manifest).

Full guarantees, code examples, and the Android/iOS equivalents are documented under Manifest interception on the Break Manifest page.

SessionConfig startSession()

GamConfig optional

Example

const sdk = new OptiViewAds({
  player: new HlsJsAdapter(hls, video),
  container: document.getElementById('container'),
  playerContainer: document.getElementById('playerContainer'),
  createAdAdapter: (adContainer) => {
    const adVideo = document.createElement('video');
    adContainer.appendChild(adVideo);
    const adHls = new Hls();
    adHls.attachMedia(adVideo);
    return new HlsJsAdapter(adHls, adVideo);
  },
  gam: {
    streamActivityMonitorId: 'my-debug-session',
  },
  debug: false,
});

Simplified setup with @dolby-optiview/ads-sdk

Import OptiViewAds from @dolby-optiview/ads-sdk to drop the createAdAdapter boilerplate — the ad player defaults to HLS.js (with a native <video> fallback). Use adPreload: 'auto' to enable single-decoder preloading on Smart TVs.

import { OptiViewAds, HlsJsAdapter } from '@dolby-optiview/ads-sdk';

const sdk = new OptiViewAds({
  player: new HlsJsAdapter(hls, video),
  container: document.getElementById('container'),
  // createAdAdapter omitted -> default HLS.js ad player (native fallback)
  adPreload: 'auto',
});

Android (Kotlin)

OptiViewAdsConfig (com.dolby.optiview.ads.sdk) carries the org-level options. The web-only DOM fields (container, playerContainer, createAdAdapter) do not exist on Android — the ad surface is owned by the OverlayAdRenderer you pass to the OptiViewAds constructor (its overlayContainer FrameLayout is the Android equivalent of container).

SessionConfig(manifestUrl, assetParameters = emptyMap()) and GamConfig(streamActivityMonitorId? = null) mirror the web shapes.

import com.dolby.optiview.ads.sdk.*

val sdk = OptiViewAds(
    config = OptiViewAdsConfig(
        player = ExoPlayerAdapter(contentPlayer),
        adPreload = AdPreloadMode.PARALLEL,
        chaining = ChainingConfig(enabled = true, maxGapSeconds = 2.0),
        tuneIn = TuneInConfig(enabled = true, minBreakDurationSeconds = 5.0),
        continueContentDuringBreak = true,
        diagnostics = DiagnosticsConfig(bufferSize = 200),
        gam = GamConfig(
            streamActivityMonitorId = "my-debug-session",
        ),
        debug = false,
    ),
    renderer = OverlayAdRenderer(context, overlayContainer, contentAdapter, gamConfig = gam),
    manifestSource = HttpManifestSource(scope),
    ticker = CoroutineSchedulerTicker(scope),
)

iOS / tvOS (Swift)

OptiViewAdsConfig (OptiViewAdsSDK, re-exported by OptiViewAdsRuntime) carries the org-level options. As on Android, the web-only DOM fields are omitted — the ad surface is owned by the OverlayAdRenderer (its overlayContainer UIView). continueContentDuringBreak is not supported on iOS/tvOS yet; Apple integrations retain pause/resume behavior.

SessionConfig(manifestUrl:assetParameters:) and GamConfig(streamActivityMonitorId:) mirror the web shapes.

import OptiViewAdsRuntime

let gam = GamConfig(
    streamActivityMonitorId: "my-debug-session"
)

let sdk = OptiViewAds(
    config: OptiViewAdsConfig(
        player: AVPlayerAdapter(player: contentPlayer),
        adPreload: .parallel,
        chaining: ChainingConfig(enabled: true, maxGapSeconds: 2.0),
        tuneIn: TuneInConfig(enabled: true, minBreakDurationSeconds: 5.0),
        continueContentDuringBreak: true,
        diagnostics: DiagnosticsConfig(bufferSize: 200),
        debug: false,
        gam: gam
    ),
    renderer: OverlayAdRenderer(overlayContainer: overlayContainer, contentPlayer: contentAdapter, gamConfig: gam),
    manifestSource: URLSessionManifestSource(),
    ticker: DispatchSchedulerTicker()
)

Web

startSession(config: SessionConfig): Promise<void>

Starts manifest polling and (if GAM is configured) initializes the IMA stream session. Resolves when the first manifest has been fetched successfully.

await sdk.startSession({
  manifestUrl: 'https://manifest.example.com/v1/your-org/channels/d7803a87-465a-4e43-b12e-6f479be119a1',
  customAssetKey: 'my-asset-key',
  adInsertionType: 'replacement', // 'replacement' (DAR, default) | 'insertion' (DAI)
  assetParameters: { cust_params: 'genre=sports' },
});
// Now load and play your content
hls.loadSource(contentUrl);
video.play();

Immediate pre-rolls hold content automatically. When the first manifest contains a content-covering pre-roll (start: { type: 'event', event: 'start' }, or the legacy position: 'pre') with no delay (or delay: 0), the SDK holds the content player at session start — pausing it and re-pausing if your own play() (above) starts it — so no content frames are shown before the ad. The pre-roll begins once the content player reports its media is loaded, or after 10 seconds. If content fails to load first, the pre-roll is cancelled and the SDK reports DA-PREROLL-CANCELLED-CONTENT-ERROR. The hold is released the moment the pre-roll begins (the break then owns content pause/resume) and on endSession(). A delay > 0 pre-roll plays content first: the delay counts played media time from the first content frame (paused time and seeks do not count). Reported via the DA-PREROLL-CONTENT-HELD diagnostic.

adInsertionType (DAR vs DAI, SGAI only). Controls how a break relates to the content timeline. replacement (DAR, the default) keeps the historical resume behaviour — the replaced content window is skipped only when a break carries an explicit resumeOffset. This is intended, not a bug: without a manifest resumeOffset, DAR resumes content from the same position the break started at (the classic "replace this window of content with an ad, then continue from where it left off" model); set resumeOffset on the break when you want DAR to skip forward past the replaced window. insertion (DAI) resumes content at the exact pre-break position. A break's manifest resumeOffset overrides the mode default in both cases. Resume-seek is applied on the positional pts and mediatime timebases for content-pausing break formats; it is ignored in SSAI mode (the stitcher controls insertion server-side, reported via the DA-INSERTION-TYPE-IGNORED-SSAI diagnostic). The demo's Ad Insertion Type selector drives this (and the ?adInsertionType= URL param). The dedicated VOD (DAR/DAI) demo page lets you contrast the two against your own VOD asset and break manifest: pick DAR or DAI, paste a PTS mid-roll manifest (provisioned via the break-manifest server — the hosted one on the deployed demo, or a local one under npm run dev), and watch the resume behaviour differ on break end.

endSession(): void

Stops manifest polling and resets the GAM session. Call this when the user navigates away, changes channel, or stops playback.

endSession() is for channel changes made by the application (a different manifestUrl). When the backend re-points the same manifest URL to another ads channel, the SDK handles it inside the running session and emits adchannelchange — see Channel switch on the Manifest page.

On an ads-channel switch, delivery mode is resolved again. The adchannelchange event reports previousDeliveryMode and deliveryMode; after an ssai to sgai switch, load the content stream in the application after receiving the event.

sdk.endSession();

updateAssetParameters(params: Record<string, string>): void

Replaces the live-update layer of the asset parameters. Useful for changing targeting (a sport segment change, a consent update) without restarting the session.

The per-key precedence is SessionConfig.assetParameters < updateAssetParameters() < the manifest session layer (vendorConfiguration.gam.sgai[0].assetParameters or ssai[0].assetParameters) < the per-asset assetParameters map. It replaces the previous update rather than accumulating onto it.

Applies to future ad breaks — a break whose ad request has already gone out cannot be retargeted. Consumed by GAM pods (IMA ad-tag parameters) and by VAST assets (appended to the tag URL as query parameters, except inline data: tag URLs, which have no query component).

sdk.updateAssetParameters({ cust_params: 'sport=basketball' });

updateAssetParameterMacros(macros: AssetParameterMacroUpdates): void

Merges the supplied macro names into the session table. null marks a customer macro empty so parameters using it are not sent; undefined unregisters the macro so a built-in value can apply again. Names not supplied remain unchanged. An active GAM stream receives the re-resolved targeting through replaceAdTagParameters(), while VAST uses the new values on its next request. An ad already loaded is not re-requested.

sdk.updateAssetParameterMacros({ '$CUSTOM_TEAM#x27;: 'basketball', '$OLD_TEAM#x27;: undefined });

Asset-parameter macros (SessionConfig.assetParameterMacros)

type AssetParameterMacroValue = string | null | undefined;
type AssetParameterMacro = AssetParameterMacroValue | (() => AssetParameterMacroValue);
type AssetParameterMacros = Record<string, AssetParameterMacro>;

startSession() accepts asset-parameter macros as assetParameterMacros. Every full $NAME$ token found inside an asset-parameter value (from the manifest, the session, or updateAssetParameters()) is replaced by macros['$NAME#39;] when the ad request is built: a string replaces the token, null marks it empty, and a callback is invoked on every request (for values that change over time). A value may hold several macros next to literal text — "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHTquot; becomes "1920x1080". Names are case-sensitive, and $APP$ and $APP_NAME$ never collide. A $ without a closing $ is left unchanged. Break-duration macros are omitted from session-level GAM/SSAI requests. The macros are cleared by endSession().

Macro values have three states:

1. A string replaces the token.
2. null marks the macro empty. The parameter is not sent. For GAM cust_params, only the &-separated pair containing the macro is dropped. If no pair remains, the cust_params key is omitted. For VAST, the whole cust_params parameter is omitted.
3. undefined or another unresolved macro leaves the token literal. The parameter is still sent.

The built-in macros are resolved by the SDK and can be overridden by registering the same name. Their names are exported as OPTIVIEW_ASSET_PARAMETER_MACROS (USER_AGENT, PLAYER_WIDTH, PLAYER_HEIGHT, BREAK_DURATION_MS, BREAK_DURATION_SECONDS):

Resolution order and fallbacks:

1. A customer macro wins over a built-in $OPTIVIEW_* name.
2. Otherwise the built-in value is used.
3. A macro that resolves to null omits its parameter. For GAM cust_params, only the pair containing the macro is dropped. For VAST, the whole cust_params parameter is omitted.
4. An unresolved $OPTIVIEW_* name (unknown, or a registration that is / returns undefined) is kept literally in the value; the parameter is still sent and emits DA-ASSET-MACRO-UNKNOWN once per parameter key and macro (context: key, macro).
5. An unresolved complete token with any other prefix ($PUBLISHER_ID$, ${OPTIVIEW_X}, …) is kept literally in the value without a diagnostic, so vendor-side macros pass through untouched.

updateAssetParameterMacros() uses null to mark a macro empty and undefined to unregister it. DA-ASSET-PARAMETER-OMITTED reports parameters omitted because a macro resolved to null; DA-ASSET-MACRO-UNKNOWN reports unresolved built-in or registered macros.

import { OPTIVIEW_ASSET_PARAMETER_MACROS } from '@dolby-optiview/ads-sdk';

const assetParameterMacros = {
  '$SEGMENT#x27;: 'sports', // fixed value
  '$CUSTOM_TEAM#x27;: () => currentTeam(), // evaluated on every ad request
  '$CUSTOM_USER_ID#x27;: () => user?.id, // undefined → sent literally as "$CUSTOM_USER_IDquot;
  [OPTIVIEW_ASSET_PARAMETER_MACROS.USER_AGENT]: 'MyApp/2.1 (SmartTV)', // overrides the built-in
};

await sdk.startSession({
  manifestUrl,
  assetParameterMacros,
  assetParameters: {
    pod_duration: '$OPTIVIEW_BREAK_DURATION_SECONDS#x27;,
    dimensions: '$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHT#x27;, // macros inside a value → "1920x1080"
  },
});

In this demo, the Asset Parameter Macros field of the Session card takes the same map as JSON. Only strings and null can be written in JSON: {"$SEGMENTquot;: "sports", "$CUSTOM_TEAMquot;: null} sends $SEGMENT$ as sports and omits every parameter that contains $CUSTOM_TEAM$. Callbacks and undefined are not JSON; leave a macro out of the map to keep its token literal. The parsed map is passed to startSession() unchanged. The omission is visible after Load: the event log shows DA-ASSET-PARAMETER-OMITTED with the omitted key and macro, and the SDK debug log in the browser console (Preloading VAST ads: <url>) shows the tag URL without that key. After Load, the Update asset parameter macros input ($NAME$=value, $NAME$=null, $NAME$=undefined) calls updateAssetParameterMacros() for the next ad request.

destroy(): void

Tears down the entire SDK instance, releasing all resources. Call this when the player is unmounted.

sdk.destroy();

play(): Promise<void>

Proxy for contentPlayer.play(). Suppressed automatically during content-locking ad breaks (e.g. single format) so the ad is not interrupted. Prefer this over calling your player directly so break policies are honoured.

await sdk.play();

pause(): void

Proxy for contentPlayer.pause(). No-op during a content-locking ad break.

sdk.pause();

seek(time: number): void

Seek the content stream to a position in seconds. Blocked when the active break has controls.snapback: true. The SDK also listens to the native seeked event from the PlayerAdapter and will snap back automatically even if the customer seeks directly on the underlying player.

sdk.seek(180); // seek to 3:00 in the content stream

muted: boolean

Unified mute state. Reading or writing sdk.muted always targets whichever player is currently audible — the ad player while a break is playing, the content player otherwise — so a single mute control works correctly across break transitions in both directions. Setting it also bridges into IMA for a VAST/CSAI ad in progress, since IMA drives its own audio path independently of the underlying <video> element.

sdk.muted = true; // mute whatever is currently playing
const isMuted = sdk.muted;

volume: number

Unified volume (0-1). Same effective-player targeting as muted above.

sdk.volume = 0.5;

Event: volumechange

Fires whenever the unified mute/volume state changes — via the muted/volume setters above, a direct mutation of the content or ad element that the SDK's internal sync picked up, or an IMA CSAI ad's own UI. Carries the resulting muted/volume values so a UI can keep a mute button's label correct without polling:

muteButton.onclick = () => {
  sdk.muted = !sdk.muted;
};
sdk.addEventListener('volumechange', (e) => {
  muteButton.textContent = e.muted ? 'Unmute' : 'Mute';
});

Lifecycle example

// App startup
const sdk = new OptiViewAds({ ... });

// User starts watching a channel
await sdk.startSession({ manifestUrl, customAssetKey });
hls.loadSource(channelUrl);

// User switches to another channel
sdk.endSession();
await sdk.startSession({ manifestUrl: newManifestUrl, customAssetKey: newKey });
hls.loadSource(newChannelUrl);

// App teardown
sdk.destroy();

Android (Kotlin)

The lifecycle methods mirror the web API. startSession is a suspend function (call it from a coroutine); the rest are synchronous. The method set is startSession / endSession / updateAssetParameters / updateAssetParameterMacros / play / pause / seek / destroy, plus isSessionActive() / isAdPlaying().

// User starts watching a channel
scope.launch {
    sdk.startSession(
        SessionConfig(
            manifestUrl = "https://manifest.example.com/v1/your-org/channels/d7803a87-465a-4e43-b12e-6f479be119a1",
            customAssetKey = "my-asset-key",
            assetParameters = mapOf(
                "cust_params" to "genre=sports",
                "dimensions" to "\$OPTIVIEW_PLAYER_WIDTH\$x\$OPTIVIEW_PLAYER_HEIGHT\quot;, // macros inside a value → "1920x1080"
            ),
            assetParameterMacros = mapOf("\$CUSTOM_TEAM\quot; to { currentTeam() }),
        ),
    )
    contentPlayer.setMediaItem(MediaItem.fromUri(channelUrl))
    contentPlayer.prepare()
    contentPlayer.playWhenReady = true
}

// Update targeting mid-session (no restart)
sdk.updateAssetParameters(mapOf("cust_params" to "sport=basketball"))
sdk.updateAssetParameterMacros(mapOf("\$CUSTOM_TEAM\quot; to { "lakers" }))

// Switch channel
sdk.endSession()
scope.launch { sdk.startSession(SessionConfig(manifestUrl = newManifestUrl, customAssetKey = newKey)) }

// Teardown (then release your ExoPlayer)
sdk.destroy()

iOS / tvOS (Swift)

startSession is async throws (call it from a Task); the rest are synchronous. Same method set as Android.

// User starts watching a channel
Task {
    do {
        try await sdk.startSession(
            SessionConfig(
                manifestUrl: "https://manifest.example.com/v1/your-org/channels/d7803a87-465a-4e43-b12e-6f479be119a1",
                customAssetKey: "my-asset-key",
                assetParameters: [
                    "cust_params": "genre=sports",
                    "dimensions": "$OPTIVIEW_PLAYER_WIDTH$x$OPTIVIEW_PLAYER_HEIGHTquot; // macros inside a value → "1920x1080"
                ],
                assetParameterMacros: ["$CUSTOM_TEAMquot;: { currentTeam() }]
            )
        )
        contentPlayer.replaceCurrentItem(with: AVPlayerItem(url: channelUrl))
        contentPlayer.play()
    } catch {
        print("startSession failed:", error)
    }
}

// Update targeting mid-session (no restart)
sdk.updateAssetParameters(["cust_params": "sport=basketball"])
sdk.updateAssetParameterMacros(["$CUSTOM_TEAMquot;: { "lakers" }])

// Switch channel
sdk.endSession()
Task { try await sdk.startSession(SessionConfig(manifestUrl: newManifestUrl, customAssetKey: newKey)) }

// Teardown
sdk.destroy()

Web

TypeScript types

// Base — all events extend this
interface OptiViewAdsEvent {
  type: string;
  timestamp: number;
}

// Break events
sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  // e.break.id, e.break.duration, e.break.start
});

// Ad events — one pair per ad, including each creative of a multi-ad GAM pod
sdk.addEventListener('adbegin', (e: AdBeginEvent) => {
  // e.asset.id, e.asset.type, e.adIndex, e.totalAds, e.format ('single' | 'double' | …)
  // e.adId / e.creativeId — IMA's ids, set only for the ads of a GAM pod
  console.log(`Ad ${e.adIndex + 1} of ${e.totalAds}`);
});

// Quartiles carry adIndex/totalAds when the SDK knows which ad they belong to
// (the ads of a GAM pod), so repeated cycles in one pod stay attributable.
sdk.addEventListener('admidpoint', (e: AdMidpointEvent) => {
  trackMidpoint(e.asset.id, e.adIndex, e.totalAds);
});

// Error events — covers both ad and content playback (check e.source)
sdk.addEventListener('aderror', (e: AdErrorEvent) => {
  console.error(`[${e.source}]`, e.error.message);
  // For ad errors the SDK automatically recovers — content will resume
});

// Buffering / playback state — fires for both content and ad (check e.source)
sdk.addEventListener('waiting', (e: WaitingEvent) => {
  if (e.source === 'content') showSpinner();
});
sdk.addEventListener('playing', (e: PlayingEvent) => {
  if (e.source === 'content') hideSpinner();
});

// Ad progress — track ad position to drive a custom progress bar
sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const pct = (e.currentTime / e.duration) * 100;
  progressBar.style.width = `${pct}%`;
});

Unsubscribing

const handler = (e) => console.log(e);
sdk.addEventListener('adbreakbegin', handler);
// Later:
sdk.removeEventListener('adbreakbegin', handler);

Building a custom player UI

Replace the browser's native controls with your own UI so you can:

• Hide controls during ad breaks and show a countdown toast instead.
• Route play/pause through the SDK so break policies (content-lock, snapback) are honoured.

Key rules

• Use sdk.play() / sdk.pause() instead of video.play() / video.pause() — the SDK will no-op these during content-locking breaks, preventing the user from accidentally resuming content mid-break.
• Use sdk.seek(time) instead of setting video.currentTime directly — honours snapback enforcement. Direct player seeks are also corrected once without recursively re-seeking when the correction emits another seeked event.
• Drive your countdown from adbreakstatus — the SDK emits this event whenever the break state or countdown changes. Use sdk.getAdBreakStatus() at any time for the current status, or subscribe to adbreakstatus for live updates. The status object includes phase ('idle' | 'upcoming' | 'active' | 'complete'), secondsUntilBreak, breakRemainingSec, adsRemaining, adIndex, totalAds, and ticking. adsRemaining counts the currently playing ad while an ad plays (totalAds − adIndex) and the ads still to come after an adend (totalAds − adIndex − 1, so 0 after the last ad). breakRemainingSec follows the break's media time — for a GAM DAI pod that is the pod's single media timeline, so the countdown runs continuously across the pod's ads.
• breakWarnings config controls pre-break warnings. Set breakWarnings: { seconds: [10, 5] } to receive adbreakstatus with phase: 'upcoming' at 10s and 5s before the break.
• Dismiss the countdown on adbreakend — adbreakend fires after all assets in the break have played (or been skipped/errored).

Minimal example

<!-- Remove the native controls attribute -->
<video id="video" muted playsinline></video>

<!-- Custom controls bar (inside the player wrapper) -->
<div id="playerControls" class="player-controls">
  <button id="btnPlay">▶</button>
  <button id="btnMute">🔇</button>
  <button id="btnFullscreen">⤢</button>
</div>

<!-- Break countdown toast (positioned over the player) -->
<div id="breakToast" class="break-toast hidden">
  <span class="toast-badge">AD</span>
  <span id="toastText">Ad break</span>
</div>

sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  // Hide player controls during the break
  document.getElementById('playerControls')!.classList.remove('visible');
});

sdk.addEventListener('adbreakstatus', (e: AdBreakStatusEvent) => {
  const { status } = e;
  const toast = document.getElementById('breakToast')!;
  const text = document.getElementById('toastText')!;

  if (status.phase === 'upcoming') {
    toast.classList.add('visible');
    text.textContent = `Ad break in ${status.secondsUntilBreak}s`;
    return;
  }

  if (status.phase === 'active') {
    toast.classList.add('visible');
    if (status.ticking && status.breakRemainingSec != null) {
      text.textContent = `Ad break · ${status.breakRemainingSec}s remaining`;
    } else {
      text.textContent = 'Ad break';
    }
    return;
  }

  if (status.phase === 'idle' || status.phase === 'complete') {
    toast.classList.remove('visible');
  }
});

sdk.addEventListener('adbreakend', () => {
  // Dismiss toast and restore controls
  document.getElementById('breakToast')!.classList.remove('visible');
  document.getElementById('playerControls')!.classList.add('visible');
});

// Route play/pause through the SDK
document.getElementById('btnPlay')!.addEventListener('click', () => {
  if (video.paused) sdk.play();
  else sdk.pause();
});

Android (Kotlin)

Subscribe with addEventListener(event: OptiViewAdsEventType, handler: (OptiViewAdsEvent) -> Unit) and unsubscribe with removeEventListener(event, handler). Events are modelled as a sealed class hierarchy — when (event) narrows to the concrete subtype. Note the property is break_ (Kotlin reserves break), and ad-level events carry assetId: String rather than a rich asset object.

import com.dolby.optiview.ads.sdk.*

// Break boundaries
sdk.addEventListener(OptiViewAdsEventType.ADBREAKBEGIN) { event ->
    val e = event as AdBreakBeginEvent
    Log.d("Ads", "Break ${e.break_.id} (${e.break_.duration}s)")
}

// Individual ads
sdk.addEventListener(OptiViewAdsEventType.ADBEGIN) { event ->
    val e = event as AdBeginEvent
    Log.d("Ads", "Ad ${e.adIndex + 1}/${e.totalAds} — asset ${e.assetId} [${e.format?.value}]")
}

// Errors — covers both ad and content (check source); SDK auto-recovers for ads
sdk.addEventListener(OptiViewAdsEventType.ADERROR) { event ->
    val e = event as AdErrorEvent
    Log.e("Ads", "[${e.source.value}] ${e.error.message}")
}

// Buffering / playback state — fires for both content and ad (check source)
sdk.addEventListener(OptiViewAdsEventType.WAITING) { event ->
    if ((event as WaitingEvent).source == PlaybackSource.CONTENT) showSpinner()
}

// Ad progress — drive a custom progress bar
sdk.addEventListener(OptiViewAdsEventType.ADTIMEUPDATE) { event ->
    val e = event as AdTimeupdateEvent
    progressBar.progress = ((e.currentTime / e.duration) * 100).toInt()
}

// Unsubscribing
val handler: OptiViewAdsEventListener = { event -> Log.d("Ads", "$event") }
sdk.addEventListener(OptiViewAdsEventType.ADBREAKBEGIN, handler)
// Later:
sdk.removeEventListener(OptiViewAdsEventType.ADBREAKBEGIN, handler)

iOS / tvOS (Swift)

addEventListener(_:_:) returns a Subscription token; pass it to removeEventListener(_:_:) to unsubscribe. Events are a Swift enum with associated values — switch to read the payload, or use the convenience accessors event.type / event.timestamp / event.source / event.breakId / event.assetId / event.format.

import OptiViewAdsRuntime

// Break boundaries
sdk.addEventListener(.adbreakbegin) { event in
    if case let .adBreakBegin(brk, _, tuneIn, format) = event {
        // `tuneIn` is non-nil when the viewer joined mid-break; `format` is the ad format.
        print("Break \(brk.id) [\(format?.rawValue ?? "?")] (\(brk.duration ?? 0)s)", tuneIn.map { "tune-in, \($0.remainingSec)s left" } ?? "")
    }
}

// Individual ads
sdk.addEventListener(.adbegin) { event in
    if case let .adBegin(_, assetId, adIndex, totalAds, _, format, _, _, _, asset) = event {
        print("Ad \(adIndex + 1)/\(totalAds) — asset \(asset?.id ?? assetId) [\(format?.rawValue ?? "?")]")
    }
    // Or, regardless of case: event.format
}

// Errors — covers both ad and content (check source); SDK auto-recovers for ads
sdk.addEventListener(.aderror) { event in
    if case let .adError(source, _, _, error, _, _) = event {
        print("[\(source.rawValue)] \(error.localizedDescription)")
    }
}

// Buffering / playback state — fires for both content and ad
sdk.addEventListener(.waiting) { event in
    if event.source == .content { showSpinner() }
}

// Ad progress — drive a custom progress bar
sdk.addEventListener(.adtimeupdate) { event in
    if case let .adTimeUpdate(_, _, currentTime, duration, _, _) = event {
        progressView.progress = Float(currentTime / duration)
    }
}

// Unsubscribing — keep the returned token
let token = sdk.addEventListener(.adbreakbegin) { event in print(event.type.rawValue) }
// Later:
sdk.removeEventListener(.adbreakbegin, token)

Web

Subscribe to diagnostics

sdk.onDiagnostic((d) => {
  console.log(`[${d.level}] ${d.code} — ${d.message}`, d.context);
});

// later
sdk.offDiagnostic(handler);

A DiagnosticEvent has this shape:

interface DiagnosticEvent {
  ts: number; // epoch ms
  level: 'debug' | 'info' | 'warn' | 'error';
  code: string; // stable, e.g. 'DA-MANIFEST-FETCH-FAILED'
  category:
    | 'manifest'
    | 'session'
    | 'break'
    | 'preload'
    | 'gam'
    | 'playback'
    | 'chaining'
    | 'event'
    | 'lifecycle';
  message: string;
  context?: Record<string, unknown>; // never contains secrets
}

Export a shareable report

exportDiagnostics() returns a self-contained, redacted report — the recent diagnostic + event timeline plus a redacted config summary, the SDK version, and the user agent. It contains no secrets: asset parameter values are stripped (only hasAssetParameters is reported).

const report = sdk.exportDiagnostics();
navigator.clipboard.writeText(JSON.stringify(report, null, 2));

This is the single artifact to paste into a support ticket or feed to the AI troubleshooting assistant.

Configuration

The diagnostic ring buffer that backs exportDiagnostics() is bounded. Tune it via the diagnostics config:

new OptiViewAds({
  // ...
  diagnostics: { bufferSize: 200 }, // default 200; older records are evicted first
});

Android (Kotlin)

onDiagnostic(handler) / offDiagnostic(handler) subscribe to the stream; exportDiagnostics() returns a redacted DiagnosticReport. The codes, categories, and levels are identical to the table above.

val handler: DiagnosticHandler = { d ->
    Log.d("Ads", "[${d.level}] ${d.code} — ${d.message} ${d.context ?: ""}")
}
sdk.onDiagnostic(handler)

// later
sdk.offDiagnostic(handler)

// Shareable, redacted report for a support ticket / AI tooling
val report = sdk.exportDiagnostics()

DiagnosticEvent (com.dolby.optiview.ads.sdk):

data class DiagnosticEvent(
    val ts: Long,                        // epoch ms
    val level: DiagnosticLevel,          // DEBUG | INFO | WARN | ERROR
    val code: String,                    // stable, e.g. "DA-MANIFEST-FETCH-FAILED"
    val category: DiagnosticCategory,    // MANIFEST | SESSION | BREAK | PRELOAD | GAM
                                         // | PLAYBACK | CHAINING | EVENT | LIFECYCLE
    val message: String,
    val context: Map<String, Any?>? = null,   // never contains secrets
)

Tune the ring buffer via OptiViewAdsConfig.diagnostics = DiagnosticsConfig(bufferSize = 200).

iOS / tvOS (Swift)

onDiagnostic(_:) returns a Subscription token (pass it to offDiagnostic(_:)); exportDiagnostics() returns a redacted DiagnosticReport.

let token = sdk.onDiagnostic { d in
    print("[\(d.level)] \(d.code) — \(d.message)", d.context ?? [:])
}

// later
sdk.offDiagnostic(token)

// Shareable, redacted report
let report = sdk.exportDiagnostics()

DiagnosticEvent (OptiViewAdsSDK):

public struct DiagnosticEvent {
    public let ts: Int64                 // epoch ms
    public let level: DiagnosticLevel    // .debug | .info | .warn | .error
    public let code: String              // stable, e.g. "DA-MANIFEST-FETCH-FAILED"
    public let category: DiagnosticCategory  // .manifest | .session | .break | .preload
                                             // | .gam | .playback | .chaining | .event | .lifecycle
    public let message: String
    public let context: [String: Any]?  // never contains secrets
}

Tune the ring buffer via OptiViewAdsConfig(diagnostics: DiagnosticsConfig(bufferSize: 200)).

Web

Non-16:9 content and the SDK stage

The SDK creates a pixel-sized .dolby-stage inside the configured container. Once the content <video> reports valid intrinsic dimensions, the stage uses that media aspect ratio rather than assuming 16:9. This matters for edge-anchored overlay, double, and L-shape layouts: their percentages resolve against the painted content rectangle, including after a rendition or source change. If metadata is not available yet, the historical 16:9 geometry remains the safe fallback.

Why custom controls?

Native browser controls have no awareness of ad breaks. A user could hit pause, seek, or unmute at exactly the wrong moment during a break. Routing all interactions through the SDK prevents this:

Setup

Remove the controls attribute and position your own UI elements inside the player container:

<!-- The SDK stage -->
<div id="container" style="position:relative;">
  <!--
    Provide an explicit playerContainer that wraps ONLY the content player(s)
    (<video>, and <div id="theoPlayerEl"> if you use THEOplayer). The SDK
    resizes/repositions playerContainer into a pip corner during a
    double/L-shape break — your controls and the break toast must live
    OUTSIDE it, as direct siblings on #container, so they keep spanning the
    full stage instead of shrinking into the pip. If you omit playerContainer
    the SDK auto-wraps ALL of #container's children (including your controls)
    into its own internal wrapper, which has the same shrinking problem.
  -->
  <div id="playerContainer" style="position:absolute;inset:0;">
    <video id="video" muted playsinline></video>
  </div>

  <!-- Controls bar: a sibling of playerContainer, always spans #container -->
  <div id="playerControls" class="player-controls">
    <button id="btnPlay" aria-label="Play/Pause"></button>
    <button id="btnMute" aria-label="Mute/Unmute"></button>
    <button id="btnFullscreen" aria-label="Fullscreen"></button>
  </div>

  <!-- Break toast: also a sibling, so it always covers the full stage -->
  <div id="breakToast" class="break-toast">
    <span class="toast-badge">AD</span>
    <span id="toastText">Ad break</span>
  </div>
</div>

Routing playback through the SDK

Always call sdk.play(), sdk.pause(), and sdk.seek() — never manipulate the video element directly from your UI:

btnPlay.addEventListener('click', () => {
  if (video.paused)
    sdk.play(); // SDK will block if break is content-locking
  else sdk.pause(); // SDK will no-op if break is content-locking
});

// Seek to 3:00 — SDK will snap back if a locked break is active
btnSeek.addEventListener('click', () => sdk.seek(180));

Hiding controls during ad breaks

The SDK fires adbreakbegin and adbreakend when a break starts and ends. Use these to swap your play/seek controls for a break indicator — but keep the mute control reachable: a viewer who cannot unmute a playing pre-roll has no way to hear it. The simplest approach is to only hide the controls that don't apply during a break (play/pause, seek) rather than the whole bar, or to include a Mute button in your break-toast markup too:

sdk.addEventListener('adbreakbegin', () => {
  // Keep the control bar (and its mute button) visible — do not hide it here.
  document.getElementById('breakToast')!.classList.add('visible');
});

sdk.addEventListener('adbreakend', () => {
  document.getElementById('breakToast')!.classList.remove('visible');
});

Break countdown timer

adbreakbegin gives you the total break duration via e.break.duration (seconds, may be undefined for dynamic breaks). Drive a countdown with setInterval:

let countdownTimer: ReturnType<typeof setInterval> | null = null;

sdk.addEventListener('adbreakbegin', (e: AdBreakBeginEvent) => {
  const toastText = document.getElementById('toastText')!;
  let remaining = Math.round(e.break.duration ?? 0);

  const fmt = (s: number) => (s >= 60 ? `${Math.floor(s / 60)}m ${s % 60}s` : `${s}s`);

  toastText.textContent = remaining > 0 ? `Ad break · ${fmt(remaining)} remaining` : 'Ad break';

  if (remaining > 0) {
    countdownTimer = setInterval(() => {
      remaining = Math.max(0, remaining - 1);
      toastText.textContent =
        remaining > 0 ? `Ad break · ${fmt(remaining)} remaining` : 'Ad break ending…';
      if (remaining === 0) {
        clearInterval(countdownTimer!);
        countdownTimer = null;
      }
    }, 1000);
  }
});

sdk.addEventListener('adbreakend', () => {
  clearInterval(countdownTimer!);
  countdownTimer = null;
});

For a more accurate countdown that stays in sync with actual ad playback, use adtimeupdate instead:

sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const remaining = Math.ceil(e.duration - e.currentTime);
  document.getElementById('toastText')!.textContent = `Ad break · ${remaining}s remaining`;
});

Ad progress bar

adtimeupdate fires at ~4 Hz during ad playback and includes both currentTime and duration:

sdk.addEventListener('adtimeupdate', (e: AdTimeupdateEvent) => {
  const pct = e.duration > 0 ? (e.currentTime / e.duration) * 100 : 0;
  progressBar.style.width = `${pct}%`;
});

Auto-hiding controls

Show controls on mouse interaction and hide them after a timeout during playback:

let hideTimer: ReturnType<typeof setTimeout> | null = null;

function showControls() {
  controls.classList.add('visible');
  clearTimeout(hideTimer!);
  if (!video.paused) {
    hideTimer = setTimeout(() => controls.classList.remove('visible'), 3000);
  }
}

container.addEventListener('mousemove', showControls);
video.addEventListener('pause', showControls); // keep visible when paused

Fullscreen

Request fullscreen on the SDK container (not the video element) so ad overlays and companion banners are included:

btnFullscreen.addEventListener('click', () => {
  if (!document.fullscreenElement) container.requestFullscreen();
  else document.exitFullscreen();
});

document.addEventListener('fullscreenchange', () => {
  btnFullscreen.setAttribute(
    'aria-label',
    document.fullscreenElement ? 'Exit fullscreen' : 'Fullscreen'
  );
});

Mute / volume sync

Drive mute/volume through the SDK's unified sdk.muted / sdk.volume — they always target whichever player is currently audible (the ad player during a break, the content player otherwise), so one button works correctly through break transitions in both directions. Listen for the SDK's volumechange event to keep your icon in sync without polling — it fires on every change, whether triggered by your button, a direct mutation of the content/ad element, or an IMA CSAI ad's own UI:

btnMute.addEventListener('click', () => {
  sdk.muted = !sdk.muted;
});

sdk.addEventListener('volumechange', (e) => {
  btnMute.setAttribute('aria-label', e.muted ? 'Unmute' : 'Mute');
  // swap icon here
});

Current-time indicator

Show the elapsed content time by polling the player on a short interval and formatting currentTime. Reading the player's currentTime works the same way across HLS.js / Shaka / THEOplayer / native, so a single poll drives the label:

const fmt = (seconds: number) => {
  if (!Number.isFinite(seconds) || seconds <= 0) return '0:00';
  const t = Math.floor(seconds);
  const h = Math.floor(t / 3600);
  const m = Math.floor((t % 3600) / 60);
  const ss = String(t % 60).padStart(2, '0');
  return h > 0 ? `${h}:${String(m).padStart(2, '0')}:${ss}` : `${m}:${ss}`;
};

const timer = setInterval(() => {
  timeIndicator.textContent = fmt(video.currentTime);
}, 250); // ~4 Hz

// On teardown: clearInterval(timer);

Keep the indicator inside #playerControls so it auto-hides during ad breaks alongside the rest of your controls (the break toast covers the ad). The demo factors this into a shared formatPlayerTime() / createTimeIndicator() helper used by every demo page.

Skip forward / back

Add skip buttons that jump the content timeline by a fixed offset. Route them through sdk.seek() and clamp the target to the playable range so you never seek past the end (or before the start). Because the seek goes through the SDK, it is a no-op without an active session and is suppressed during snapback breaks:

const clampSeekTarget = (current: number, delta: number, duration: number) => {
  const target = (Number.isFinite(current) ? current : 0) + delta;
  if (target < 0) return 0;
  if (Number.isFinite(duration) && target > duration) return duration; // live: skip upper clamp
  return target;
};

function skip(delta: number) {
  sdk.seek(clampSeekTarget(video.currentTime, delta, video.duration));
}

btnBack15.addEventListener('click', () => skip(-15));
btnFwd30.addEventListener('click', () => skip(30));

The demo's VOD page wires exactly this (−15s / +30s) with the shared clampSeekTarget() helper in packages/demo/src/seek.ts. The buttons live inside #playerControls, so they auto-hide during ad breaks.

Remembered session fields

The demo's Player page remembers your per-user Org ID, Channel ID, Custom Asset Key, Content URL, and Ad Tag Parameters in localStorage, so edits survive a reload. The built-in defaults stay as the fallback for a fresh browser, and a Reset to defaults link under the Load button clears the saved values and restores them. This is a demo-page convenience (helper in packages/demo/src/field-storage.ts); the SDK itself stores nothing. URL query-param overrides used by the e2e suite still take precedence over stored values.

Predefined configurations via URL (?presets)

The Player page can be seeded with named, fully-formed configurations passed in the URL — handy for sharing reproducible setups without hand-editing the form. Pass a base64-encoded JSON array of configuration objects in the ?presets= query parameter. When present, a Predefined Configurations card appears at the top of the config column; choosing an entry fills the whole form and auto-loads it. The first entry is auto-selected and loaded on page open. With no ?presets parameter, the card is hidden and the page behaves exactly as before (the manual form stays available either way).

Every field on the page is configurable. All fields except name are optional — an omitted field keeps the form's current/default value. The one exception is preRoll: it is a full on/off toggle, so a preset that omits preRoll (or sets "enabled": false) turns pre-roll OFF. This means switching from a pre-roll preset to one without never inherits the previous pre-roll injection.

[
  {
    "name": "Sponsor A — SGAI DAR", // required, non-empty; the selector label
    "mode": "sgai", // "sgai" | "ssai"
    "player": "hlsjs", // "hlsjs" | "shaka" | "theo" | "native"
    "manifestBaseUrl": "https://us.staging.ads.sneezysparrow.com/manifest/v1",
    "gam": true, // Enable GAM
    "networkCode": "23285652104",
    "orgId": "0bda787b-…",
    "channelId": "d7803a87-…",
    "customAssetKey": "assetkey_michel",
    "adInsertionType": "replacement", // "replacement" (DAR) | "insertion" (DAI)
    "contentUrl": "https://…/main.m3u8",
    "assetParams": { "iu": "/23285652104/dcoffey-v2-adunit" }, // object or JSON string
    "preRoll": { "enabled": true, "format": "single", "delaySeconds": 0 },
    "stitcherBaseUrl": "http://localhost:4600", // SSAI only — demo composes the master URL from it + orgId/channelId
    "stitcherOriginUrl": "https://…/main.m3u8",
    "maxBitrate": 2000000,
    "ssaiAutoplay": true,
    "stitcherPort": "4600",
    "snapPolicy": "nearest", // "nearest" | "start" | "end"
  },
]

Build the parameter by base64-encoding the JSON array (standard or URL-safe base64 is accepted), e.g. in the browser console:

const presets = [{ name: 'Sponsor A', orgId: '…', channelId: '…' }];
location.search = '?presets=' + encodeURIComponent(btoa(JSON.stringify(presets)));

Unknown keys are ignored and unknown enum values (mode, player, insertion type, snap policy, pre-roll format) are skipped with a logged warning, so a config is forward-compatible. A malformed, empty, or non-array ?presets value is ignored (with one warning in the event log) and the card is not shown. Decoding/applying is handled by the unit-tested packages/demo/src/demo-presets.ts helper (decodeUrlPresets / applyPreset); demo only — no SDK/core change.

Preset Builder

You don't have to hand-write that base64 array. The Preset Builder page (sidebar → Preset Builder, /preset-builder.html) lets you visually assemble one or more presets, generates the shareable URL-safe ?presets= link and the raw JSON live, and offers Copy + Open in Player. You can also paste an existing ?presets URL (or base64 token) to import and edit it — a full round-trip. The builder reuses the same demo-presets.ts primitives (encodeUrlPresetsSafe / decodeUrlPresets) and the pure packages/demo/src/preset-builder-model.ts helper (buildPreset / presetToValues / presetsToUrl / urlToPresets), so the links it produces are exactly what the Player page consumes.

Android (Kotlin)

The SDK plays ads on its own PlayerView inside the overlayContainer FrameLayout you pass to OverlayAdRenderer, stacked above your content surface. Build your own controls (or use a Compose overlay) and follow the same rules:

• Provide an overlay container above your content PlayerView — a FrameLayout matching the content bounds, passed to OverlayAdRenderer(context, overlayContainer, contentAdapter).
• Route playback through the SDK — call sdk.play() / sdk.pause() / sdk.seek(seconds) instead of touching the ExoPlayer directly, so content-lock and snapback are honoured.
• Swap controls for a break indicator on ADBREAKBEGIN / ADBREAKEND.
• Drive a countdown from the ADTIMEUPDATE event (currentTime / duration) or from break_.duration.

// Hide your controls + show a break indicator during the break
sdk.addEventListener(OptiViewAdsEventType.ADBREAKBEGIN) {
    playerControls.isVisible = false
    breakToast.isVisible = true
}
sdk.addEventListener(OptiViewAdsEventType.ADBREAKEND) {
    breakToast.isVisible = false
    playerControls.isVisible = true
}

// Countdown that stays in sync with actual ad playback
sdk.addEventListener(OptiViewAdsEventType.ADTIMEUPDATE) { event ->
    val e = event as AdTimeupdateEvent
    val remaining = kotlin.math.ceil(e.duration - e.currentTime).toInt()
    toastText.text = "Ad break · ${remaining}s remaining"
}

// Route the play/pause button through the SDK (no-op during content-locking breaks)
playPauseButton.setOnClickListener {
    if (contentPlayer.isPlaying) sdk.pause() else sdk.play()
}

iOS / tvOS (Swift)

The SDK plays ads on its own AVPlayer in an AVPlayerLayer inside the overlayContainer UIView you pass to OverlayAdRenderer, stacked above your content surface. The same rules apply:

• Provide an overlay container above your content surface — a UIView matching the content bounds, passed to OverlayAdRenderer(overlayContainer:contentPlayer:).
• Route playback through the SDK — call sdk.play() / sdk.pause() / sdk.seek(seconds) instead of touching the AVPlayer directly.
• Swap controls for a break indicator on .adbreakbegin / .adbreakend.
• Drive a countdown from the .adtimeupdate event, or from the break duration.

// Hide your controls + show a break indicator during the break
sdk.addEventListener(.adbreakbegin) { _ in
    playerControls.isHidden = true
    breakToast.isHidden = false
}
sdk.addEventListener(.adbreakend) { _ in
    breakToast.isHidden = true
    playerControls.isHidden = false
}

// Countdown that stays in sync with actual ad playback
sdk.addEventListener(.adtimeupdate) { event in
    if case let .adTimeUpdate(_, _, currentTime, duration, _) = event {
        let remaining = Int(ceil(duration - currentTime))
        toastLabel.text = "Ad break · \(remaining)s remaining"
    }
}

// Route the play/pause button through the SDK (no-op during content-locking breaks)
playPauseButton.addAction(UIAction { _ in
    contentPlayer.timeControlStatus == .playing ? sdk.pause() : sdk.play()
}, for: .touchUpInside)

Manifest interception

Two optional SGAI hooks let you intercept the break manifest on the client — without standing up a proxy — at the two natural points around the fetch. Both run on the initial fetch and every subsequent poll.

• interceptManifestRequest runs before the network request (rewrite URL, add headers, or mock the response).
• interceptManifestResponse runs after fetch + validation (transform the parsed BreakManifest).

Request interception (interceptManifestRequest)

The interceptManifestRequest hook is invoked before the SDK fetches the manifest, so you can redirect the request, attach headers, or short-circuit the network entirely with a mocked response. It is primarily a testing aid (point the SDK at a fixture, or exercise header-based auth) but is a supported production hook.

Return one of:

• a ManifestRequest ({ url, headers? }) — fetch this (possibly rewritten) URL with the given headers;
• a ManifestMockResponse ({ body }) — skip the network and use body (a raw JSON string or object) as the fetched manifest body. The mock body goes through the normal parse + validation path — an invalid body still fails validation, and interceptManifestResponse (if set) still runs afterward;
• nothing (void/undefined) — fetch unchanged.

Failure is non-fatal: if the hook throws (or its promise rejects), the SDK emits DA-MANIFEST-REQUEST-INTERCEPT-FAILED and falls back to the normal network fetch of the original URL. May be async.

import { OptiViewAds, type ManifestRequest } from '@dolby-optiview/ads-sdk-core';

const sdk = new OptiViewAds({
  // ...
  // Add an auth header to every manifest request (initial fetch + every poll):
  interceptManifestRequest: (request: ManifestRequest) => ({
    ...request,
    headers: { ...request.headers, Authorization: `Bearer ${token}` },
  }),
});

// Or short-circuit the network with a fixture (great for tests):
new OptiViewAds({
  // ...
  interceptManifestRequest: () => ({ body: JSON.stringify(myFixtureManifest) }),
});

Response interception (interceptManifestResponse)

Some integrations need to adjust the break manifest on the client — inject a pre-roll, drop a break, rewrite an asset URL, or layer in client-side targeting — without standing up a proxy. The optional interceptManifestResponse SDK config hook is invoked after the SDK has fetched and validated the manifest, on the initial fetch and on every subsequent poll, so you can transform it before it is scheduled.

Key guarantees:

• Typed, never raw. The callback receives the parsed BreakManifest (normalized variants arrays, parsed numbers/enums) — never the raw JSON. An invalid manifest fails validation before the hook runs, so it is never called with garbage.
• Its return value is used as-is. Return the (possibly new) BreakManifest to schedule; it is used directly, without re-validation. Returning the input unchanged is a no-op.
• Runs on every poll. Live channels re-poll; the hook is applied each time, so keep it pure/idempotent (e.g. guard against injecting the same break twice).
• Failure is non-fatal. If the hook throws (or its promise rejects), the SDK emits the DA-MANIFEST-INTERCEPT-FAILED diagnostic and falls back to the unmodified parsed manifest — the fetch/poll does not fail.
• May be async. Return a Promise<BreakManifest> to do async work (the poll awaits it).

import { OptiViewAds, type BreakManifest } from '@dolby-optiview/ads-sdk-core';

const sdk = new OptiViewAds({
  // ...
  interceptManifestResponse: (manifest: BreakManifest, ctx) => {
    // Inject a client-side pre-roll, idempotently (runs on every poll).
    if (manifest.breaks.some((b) => b.id === 'my-preroll')) return manifest;
    return {
      ...manifest,
      breaks: [
        {
          id: 'my-preroll',
          start: { type: 'event', event: 'start' },
          duration: 15,
          variants: [
            /* ... */
          ],
        },
        ...manifest.breaks,
      ],
    };
  },
});