ads-sdk-core/com.dolby.optiview.ads.core

Package-level declarations

The Break Manifest model (BreakManifest, Break, Asset, BreakFormat, Timebase), the PlayerAdapter contract with its events and timed-metadata cues, the preload / insertion / delivery mode types, the exceptions the SDK throws, and the diagnostic category and level types.

Types

AdChannelChangeReason

enum AdChannelChangeReason : Enum<AdChannelChangeReason>

Why a polled Break Manifest counts as a switch to another ads channel. Carried on the adchannelchange event as its reason.

AdInsertionType

enum AdInsertionType : Enum<AdInsertionType>

Ad insertion type — how an ad break relates to the content timeline. Mirrors the TS AdInsertionType ('replacement' = DAR, 'insertion' = DAI).

Asset

data class Asset(val id: String, val type: String? = null, val uri: String? = null, val uris: List<AssetUri>? = null, val mediaType: String? = null, val duration: Double? = null, val vendor: String? = null, val vendorParameters: Map<String, Any?>? = null, val assetParameters: Map<String, String>? = null, val companion: Asset? = null, val interaction: Interaction? = null)

A single ad asset. Only the fields the SDK orchestrator/sequencer need are modeled here (the id drives the ad-event sequence); rich asset detail (uri/mediaType/companion/vendor params) is added in the player phase.

AssetParameterMacro

typealias AssetParameterMacro = () -> AssetParameterMacroValue

A customer macro: a zero-argument callback evaluated every time an ad request is built, registered per token name in SessionConfig.assetParameterMacros. Return AssetParameterMacroValue.of of a string for a constant.

AssetParameterMacroValue

sealed class AssetParameterMacroValue

What a macro resolves to when an ad request is built.

AssetUri

data class AssetUri(val value: String, val targeting: Targeting? = null)

One candidate URI for an asset, with optional targeting (mirrors the TS AssetUri). Selected by Asset.resolveUri.

Break

data class Break(val id: String, val start: Any, val duration: Double, val resumeOffset: Double? = null, val controls: Controls? = null, val variants: List<BreakVariant> = emptyList(), val position: String? = null, val delay: Double? = null)

A single ad break. The portable brain (BreakScheduler) reads only id, start, and duration; the SDK orchestrator additionally uses controls (snapback/seek policy) and variants (to build the sequencer's SeqBreak).

BreakEvent

enum BreakEvent : Enum<BreakEvent>

Spec BreakEvent values. START and END are scheduled, PAUSE is owned by the pause-ad controller.

BreakFormat

enum BreakFormat : Enum<BreakFormat>

The supported break formats (mirrors the TS BreakFormat).

BreakManifest

data class BreakManifest(val version: String, val timebase: Timebase, val breaks: List<Break>, val polling: Polling? = null, val adStartDelay: Double? = null, val organizationId: String? = null, val channelId: String? = null, val eventId: String? = null, val vendorConfiguration: List<VendorConfiguration> = emptyList(), val delivery: List<DeliveryRule>? = null)

The root Break Manifest structure.

BreakPosition

enum BreakPosition : Enum<BreakPosition>

The only supported position value: a pre-roll relative to session start.

BreakVariant

data class BreakVariant(val format: BreakFormat, val assets: List<Asset> = emptyList(), val position: OverlayPosition? = null, val size: OverlaySize? = null, val opacity: Double? = null, val targeting: Targeting? = null, val rawFormat: String = format.value)

A break variant (format + ordered assets). The portable brain reads format/rawFormat/targeting/assets (variant selection — see selectVariantDetailed); the overlay layout fields (position/size/opacity) are resolved by the platform renderer and are populated only for BreakFormat.OVERLAY variants (null otherwise). Companion remains out of the portable model.

BreakWarningsConfig

data class BreakWarningsConfig(val seconds: List<Double> = emptyList())

Pre-break warnings (OptiViewAdsConfig.breakWarnings): the SDK emits an adbreakstatus event with phase = upcoming at each threshold.

ChainingConfig

data class ChainingConfig(val enabled: Boolean, val maxGapSeconds: Double)

Consecutive-break chaining (OptiViewAdsConfig.chaining): when one break ends and the next starts within maxGapSeconds, the SDK plays the next break at once instead of resuming content for the gap.

Clock

fun interface Clock

Wallclock time source for the scheduler. Abstracts the system clock so a driver (e.g. the conformance harness) can step wallclock time deterministically. Mirrors Clock in packages/core/src/services/BreakScheduler.ts.

ContentVideoSize

data class ContentVideoSize(val width: Int, val height: Int)

Intrinsic pixel dimensions of the content video, as reported by the player.

ContentVideoSizeProvider

interface ContentVideoSizeProvider

Optional capability a PlayerAdapter can implement to report the content video's intrinsic dimensions.

Controls

data class Controls(val skipOffset: Double? = null, val snapback: Boolean? = null)

User control options during a break (mirrors the TS Controls).

DeliveryMode

enum DeliveryMode : Enum<DeliveryMode>

Delivery architecture a DeliveryRule can select (mirrors the TS DeliveryMode).

DeliveryRule

data class DeliveryRule(val mode: String, val targeting: Targeting? = null)

One delivery-steering rule (mirrors the TS DeliveryRule). A rule without targeting matches every client (the manifest's default); a targeted rule matches only its device type.

DeviceType

enum DeviceType : Enum<DeviceType>

Device class used for per-URI asset targeting (mirrors the TS DeviceType).

DiagnosticCategory

enum DiagnosticCategory : Enum<DiagnosticCategory>

Functional area a diagnostic relates to.

DiagnosticCodeInfo

data class DiagnosticCodeInfo(val category: DiagnosticCategory, val level: DiagnosticLevel, val summary: String)

Static metadata describing a diagnostic code.

DiagnosticLevel

enum DiagnosticLevel : Enum<DiagnosticLevel>

Severity of a diagnostic record.

DoubleBoxAudio

enum DoubleBoxAudio : Enum<DoubleBoxAudio>

Which side keeps audio during a double-format break.

EventTrigger

data class EventTrigger(val event: String, val delay: Double? = null)

Spec EventTrigger: a break start bound to a playback event instead of a timeline position. event is kept raw so unknown values stay forward-compatible; delay is seconds of played content after the event.

GamPodAdInfo

data class GamPodAdInfo(val adPosition: Double? = null, val totalAds: Double? = null, val adId: String? = null, val creativeId: String? = null)

One IMA pod-ad report, normalized off AdEvent.getAd().getAdPodInfo() by the render layer so this module never sees an IMA object.

GamSessionIdentity

data class GamSessionIdentity(val networkCode: String, val customAssetKey: String)

The GAM stream identity, as used to create the IMA/DAI session.

GamVendorParameters

data class GamVendorParameters(val type: String, val eabnVersion: String, val networkCode: String, val customAssetKey: String)

The vendorParameters of a GAM pod-serving asset, validated. The EABN version selects the pod URL path segment (/pod/ vs /ad_break_id/).

InsertionMode

enum InsertionMode : Enum<InsertionMode>

Resolved ad-insertion strategy: the auto sentinel resolves to one of these.

Interaction

data class Interaction(val clickThrough: String? = null)

Interaction options for an asset (mirrors the TS Interaction).

ManifestService

class ManifestService

Parses and validates break manifests. Mirrors the validation in packages/core/src/services/ManifestService.ts (parseManifest) — error messages are part of the cross-language contract and must match the TS reference byte-for-byte (the conformance harness diffs them).

ManifestSignatureKey

data class ManifestSignatureKey(val kid: String, val publicKey: ByteArray)

A trusted Ed25519 verification key, resolved by the protected kid.

OptiViewAssetParameterMacros

object OptiViewAssetParameterMacros

The built-in asset-parameter macros the SDK resolves itself. A customer macro registered under one of these names in SessionConfig.assetParameterMacros takes precedence over the built-in value.

OptiViewInternalApi

@Target(allowedTargets = [AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.TYPEALIAS])

annotation class OptiViewInternalApi

Marks a declaration the SDK modules share with each other but that is not part of the supported public API: it can change or disappear in any release and is left out of the API reference. Using it from an app produces a compiler warning; opt in with @OptIn(OptiViewInternalApi::class) to accept that.

OverlayPosition

data class OverlayPosition(val top: Double? = null, val bottom: Double? = null, val left: Double? = null, val right: Double? = null)

Position of an overlay ad within the player surface, as fractions 0.0-1.0 of the surface (mirrors the TS OverlayPosition). Only one of {top, bottom} and one of {left, right} is typically supplied; the renderer converts these to platform layout. Brain-agnostic — only the overlay renderer reads them.

OverlaySize

data class OverlaySize(val width: Double, val height: Double)

Size of an overlay ad as fractions 0.0-1.0 of the player surface (mirrors the TS OverlaySize).

PauseAdResolution

data class PauseAdResolution(val breakInfo: Break, val asset: Asset, val source: String, val mediaType: String)

The resolved pause ad to display: the originating break, its single asset, how the asset is sourced, and whether it is an image or a video. The renderer uses source to decide whether to load the URL directly (static) or fetch + parse the VAST creative first (vast), and mediaType to decide whether to render an image overlay or a muted, play-once video. Mirrors the TS PauseAdResolution.

PlayerAdapter

interface PlayerAdapter

The abstraction layer between the SDK and any content player — the Kotlin mirror of packages/core/src/interfaces/PlayerAdapter.ts.

PlayerAdapterEvent

enum PlayerAdapterEvent : Enum<PlayerAdapterEvent>

Event types a PlayerAdapter must forward (mirrors the TS PlayerAdapterEvent).

PlayerAdapterEventHandler

typealias PlayerAdapterEventHandler = (event: Any?) -> Unit

A player event handler. The optional payload carries adapter-specific detail (e.g. a media error or TimedMetadataCue).

Polling

data class Polling(val idle: Double, val active: Double)

Manifest refresh cadence (mirrors the TS Polling). idle is the seconds between polls when no break is active; active is the (typically shorter) interval while a break is being rendered. Both are seconds.

PreloadMode

enum PreloadMode : Enum<PreloadMode>

Resolved preload strategy: the auto sentinel resolves to one of these.

SsaiUnavailableException

class SsaiUnavailableException(message: String) : Exception

Thrown when the manifest steers the session to ssai but no vendor configuration can provide a stitched stream. Deliberately catchable by the application (no silent fallback to sgai): the app decides which stream to play instead.

StitchedStreamVendor

data class StitchedStreamVendor(val type: String, val networkCode: String, val assetKey: String, val assetParameters: Map<String, String>? = null)

A vendor configuration entry able to serve a server-stitched stream.

Targeting

data class Targeting(val deviceType: String? = null)

Targeting criteria attached to an AssetUri (mirrors the TS Targeting).

Timebase

enum Timebase : Enum<Timebase>

Determines which time reference is used for break start times.

TimedMetadataCue

data class TimedMetadataCue(val type: String, val startTime: Double, val endTime: Double? = null, val frames: Map<String, String> = emptyMap(), val description: String? = null, val mimeType: String? = null, val id: String? = null, val schemeIdUri: String? = null, val messageData: String? = null, val raw: ByteArray? = null, val phase: String? = null)

A single in-stream timed-metadata marker surfaced by a content player — the Kotlin mirror of the TS TimedMetadataCue. Carried as the payload of a TIMEDMETADATA event; in SSAI mode the SDK forwards it to the IMA DAI stream manager for ad tracking.

TuneInConfig

data class TuneInConfig(val enabled: Boolean, val minBreakDurationSeconds: Double)

Tune-in, or join-in-progress (OptiViewAdsConfig.tuneIn): a viewer who joins while a break is already running sees the remainder of that break, unless less than minBreakDurationSeconds of it is left.

VariantSelectionInputs

data class VariantSelectionInputs(val deviceType: String? = null, val playableFormats: List<String>? = null)

Inputs the platform layer feeds into a selection (mirrors the TS shape).

VendorAdException

class VendorAdException(message: String, val vendorCode: String) : Exception

An ad playback error that carries the ad vendor's own error code (e.g. the numeric IMA/VAST AdError code), so telemetry can report it (adevc) alongside the SDK's taxonomy code. Vendor integrations wrap their errors in this type when the vendor supplies a code; errors without one stay plain exceptions.

VendorConfiguration

data class VendorConfiguration(val type: String, val values: Map<String, Any?>)

Session-level configuration for one vendor integration.

VideoQuality

enum VideoQuality : Enum<VideoQuality>

A quality target understood by the optional PlayerAdapter.setVideoQuality operation.

Properties

DEFAULT_PDT_GRACE_SECONDS

const val DEFAULT_PDT_GRACE_SECONDS: Double = 5.0

Default for OptiViewAdsConfig.pdtGraceSeconds: how long a wallclock session waits for the stream's program date time.

MANIFEST_SIGNATURE_HEADER

const val MANIFEST_SIGNATURE_HEADER: String

The header carrying the detached JWS over the manifest response body.

systemClock

val systemClock: Clock

Default Clock backed by the system clock.

Functions

getBreakEvent

fun getBreakEvent(brk: Break): String?

The playback event that triggers brk (spec event or legacy position), or null for a timeline break.

getDiagnosticCodeInfo

fun getDiagnosticCodeInfo(code: String): DiagnosticCodeInfo?

Look up the metadata for a known diagnostic code, or null if unknown.

getPostRollDelay

fun getPostRollDelay(brk: Break): Double?

Seconds after content playback ends before a post-roll triggers, or null when brk is not a post-roll.

getPreRollDelay

fun getPreRollDelay(brk: Break): Double?

Pre-roll delay in seconds of played content, or null when brk is not a START pre-roll.

hasImmediatePreRoll

fun hasImmediatePreRoll(manifest: BreakManifest): Boolean

Whether a pre-roll fires as soon as content playback starts: a delay: 0 pre-roll with no adStartDelay (an ad-free start would swallow it).

isEventTrigger

fun isEventTrigger(start: Any?): Boolean

True when start is an EventTrigger rather than a timebase position.

isPauseBreak

fun isPauseBreak(brk: Break): Boolean

True when brk is a pause ad: its start is an EventTrigger for BreakEvent.PAUSE.

isPostRollBreak

fun isPostRollBreak(brk: Break): Boolean

Whether the break is a post-roll: start: { type: 'event', event: 'end' }.

resolveBreakAsset

fun resolveBreakAsset(brk: Break?, assetId: String?): Asset?

The Asset carrying assetId within brk, searched across every variant.

resolveBreakFormat

fun resolveBreakFormat(brk: Break): BreakFormat?

Resolve the declared ad format of a break — the first (selected) variant's BreakFormat (PLAYG-182), mirroring the TS resolveBreakFormat. Surfaced on the public break/ad events. Null when the break declares no variant.

resolveUri

fun Asset.resolveUri(deviceType: DeviceType?): String?

Resolve this asset's URI for deviceType, handling both the single-string and the targeted-array manifest shapes. Prefer this over reading Asset.uri directly.