Package-level declarations

An individual ad starts playing. A GAM pod reports one adbegin per ad it was filled with.

An ad break starts and content is paused (or, for lshape_content and overlay breaks, keeps playing).

An ad break ends and content resumes.

Lifecycle phase reported by AdBreakStatus. Mirrors the TS AdBreakPhase.

Playback-gated snapshot of an ad break for UI countdowns — the Kotlin mirror of the web AdBreakStatus (packages/core/src/types/Events.ts). The SDK owns the timebase and the player-gated ticking flag; the application renders the badge/overlay. Emitted on the AdBreakStatusEvent and returned by OptiViewAds.getAdBreakStatus.

Event emitted when the status of the current or upcoming ad break changes. Carries a complete AdBreakStatus snapshot. Mirrors the TS AdBreakStatusEvent.

A polled manifest described a different ads channel and the SDK re-aligned its ad setup to it while the session and content playback continued. Fires once per switch, after a break in progress has finished and the new manifest is applied.

The viewer clicked/tapped the ad on screen (or the application called OptiViewAds.clickAd programmatically) — the Kotlin mirror of the iOS/web adclick event. Carries the asset's declared interaction.clickThrough URL when the manifest supplies one; the SDK deliberately does NOT open it — that is the application's decision.

The creative identity IMA reports for an ad of a GAM pod (PLAYG-361/362). Absent for every other asset kind, where the manifest asset already identifies the ad.

An individual ad finishes.

Playback failed. Emitted for both the content player and the SDK's ad player; source tells them apart. An ad error is not fatal: the SDK skips the asset and continues the break or resumes content.

An ad reached 25% completion.

Ad insertion strategy. auto resolves per device (iPhone/iPod → adaptive or shared-element; otherwise overlay). On Android this resolves to OVERLAY.

An ad reached 50% completion.

Ad preload strategy. auto resolves at runtime (decoder-limited devices → SINGLE_DECODER, otherwise PARALLEL).

The ad-rendering boundary — the Kotlin counterpart of the web AdPlayerController. The orchestrator (OptiViewAds) stays player-agnostic and delegates everything that touches a media surface, an overlay, or GAM/IMA to an AdRenderer. The Android runtime renderer (Media3 ad player + overlay + IMA DAI) implements this in P4b; tests and the conformance driver supply a fake.

An ad reached 75% completion.

Ad playback progressed; fires on each time update of the ad player (about 4 Hz). For a GAM pod the times describe the whole pod, not the ad on screen.

Progress callbacks the renderer fires across a single break. Ad-level callbacks carry the asset id (String), matching the portable brain's id-based break/asset model and the conformance sdkSequence shape.

Resolves the break chained immediately after the break with the given id, or null when none/disabled.

Redacted SDK configuration summary; secrets and PII-bearing fields are stripped.

Default SchedulerTicker: drives BreakScheduler.tick() from a coroutine delay loop on the supplied scope, every intervalMs ms. Pure Kotlin/JVM (no Android dependency); on Android the scope is typically the SDK's main-dispatcher scope so ticks land on the main thread.

A bounded, in-memory ring buffer of DiagnosticEvents. Retains the most recent capacity records so OptiViewAds.exportDiagnostics can produce a self-contained report without unbounded growth on long-running live sessions.

A single structured diagnostic record.

Handler for the structured diagnostic stream.

A self-contained, redacted diagnostic report suitable for support/AI tooling.

Structured diagnostics configuration.

A fetched manifest response: the exact body bytes (after transfer/content decoding) plus the detached-JWS signature header, both needed to verify the manifest before it is parsed.

Configuration for Google Ad Manager pod serving.

GAM/IMA quartile callbacks forwarded to the public SDK event stream. The adIndex/totalAds arguments attribute the quartile to a specific ad of a GAM pod (PLAYG-362); null outside per-ad pod reporting.

Redacted GAM summary for a DiagnosticReport (ad-tag-parameter VALUES omitted).

Default ManifestSource: fetches the manifest over HTTP (via an injectable ManifestFetcher), decodes JSON, and validates it through the portable, conformance-locked core ManifestService. Polling is a coroutine loop on the supplied scope. Pure Kotlin/JVM — no Android dependency.

Fetches the raw manifest response for a URL. Injected so HttpManifestSource can be unit-tested without real networking; the default is OkHttpManifestFetcher.

What a failed manifest read can say for itself. Twin of ManifestFetchEvidence in packages/core/src/services/ManifestService.ts — see there for why the field set is this small and no smaller.

Context passed to a ManifestResponseInterceptor alongside the manifest.

Diagnostic sink a ManifestSource uses to surface a failed interceptor.

A mocked manifest response. When a ManifestRequestInterceptor returns this, the SDK skips the network and uses body (raw JSON) as the fetched manifest body — parsed + validated exactly as a real network response would be.

The outgoing manifest request the SDK is about to make. A ManifestRequestInterceptor may return a (modified) copy to redirect the fetch (url) and/or attach headers.

Context passed to a ManifestRequestInterceptor alongside the request.

Customer hook to inspect/modify the manifest HTTP request before the SDK fetches it — invoked on the initial fetch and every poll, before the network call. Return a ManifestRequest to redirect/add headers, a ManifestMockResponse to short-circuit the network with a raw body (parsed + validated normally), or null to fetch unchanged. May suspend. If it throws, the SDK emits DA-MANIFEST-REQUEST-INTERCEPT-FAILED and falls back to the normal network fetch. Mirrors the web ManifestRequestInterceptor.

What a ManifestRequestInterceptor may return: a redirect/header override or a mock response.

Customer hook to inspect/modify the break manifest after the SDK has fetched and validated it, before it is scheduled/used. Invoked on the initial fetch and on every poll, with the already-parsed, typed BreakManifest — never raw JSON. Returns the manifest to use (modified or unchanged); the returned value is used directly without re-validation. May suspend. If it throws, the SDK emits DA-MANIFEST-INTERCEPT-FAILED and falls back to the un-modified parsed manifest (the fetch does not fail). Mirrors the web ManifestResponseInterceptor.

The manifest fetch + poll boundary. The portable :ads-sdk-core ManifestService only parses + validates a decoded manifest (so its validation stays conformance-locked across platforms); the actual network fetch and the polling timer are platform concerns and live behind this interface. HttpManifestSource is the default implementation (OkHttp + coroutine poll loop); tests and the conformance driver supply a fake.

OkHttp-backed ManifestFetcher. The blocking call runs on Dispatchers.IO.

The OptiView Ads SDK entry point: one instance per content player, living as long as the player. It polls the Break Manifest of the current session, schedules the breaks against the player's timeline through the configured PlayerAdapter, plays them through the AdRenderer, and reports what happens on the event stream (addEventListener) and the diagnostics stream (onDiagnostic, exportDiagnostics).

Org-level SDK configuration, fixed for the lifetime of the OptiViewAds instance. Chaining uses the brain's already-resolved ChainingConfig; the default below matches the web DEFAULT_CHAINING (enabled, 2s gap). tuneIn matches the web DEFAULT_TUNE_IN (enabled, 5s minimum remaining duration).

Base type for all SDK events.

Listener for a single OptiViewAdsEventType (registered via OptiViewAds.addEventListener).

The SDK event type tags (mirrors the TS OptiViewAdsEventType).

Which player a playback event originated from.

Playback started or resumed after stalling or pausing, on the content player or the ad player.

What the SDK is presenting right now, returned by OptiViewAds.getPresentationState.

Which media the SDK currently has on the player surface.

Selects how PTS-timebase break starts are resolved.

Invoked by a renderer when the viewer taps/clicks the ad surface during a break. The orchestrator resolves the current break/asset + clickThrough and emits the public adclick event.

Sink for structured diagnostics emitted by a renderer. The orchestrator wires this to its own diagnose(...) so renderer-side codes (e.g. DA-VAST-*) flow through the same diagnostic stream/buffer as the SDK's.

Drives the portable BreakScheduler.tick() on a fixed cadence.

Per-session configuration passed to OptiViewAds.startSession. Changes per piece of content / channel switch.

How the picture changes at the edges of a break — content to ad and back.

How a break transition is played.

Tune-in (join-in-progress) detail attached to an AdBreakBeginEvent when the viewer joined while the break was already in progress. remainingSec is the effective duration the break is presented for.

Unified audio state changed — the Kotlin mirror of the TS VolumeChangeEvent.

Playback stalled for buffering, on the content player or the ad player.

Default ad-break-cut safety margin, in seconds. A break is always hard-cut back to content at effectiveDuration + this margin at the latest, no matter how long the inserted ad media runs — the SDK never depends on the ad stream reaching its own end before returning to content. The small margin is grace so an ad whose length is close to the break duration can finish cleanly instead of having its final second(s) chopped at the exact boundary. Mirrors the web DEFAULT_AD_BREAK_CUT_SAFETY_MARGIN_SEC.

Default in-memory diagnostics ring-buffer size.

Default scheduler tick cadence (ms) — mirrors the web scheduler's 250 ms setInterval.

Default break-transition duration, in milliseconds. The same 300ms the web core uses (AdPlayerController.TRANSITION_MS) and iOS (layoutTransitionSec), so a break looks the same on every platform unless an integrator says otherwise.

Dependency-free JSON serialization for DiagnosticReport.