Skip to main content
format(), load() and awaitInitialization() may be called from any dispatcher (their work runs on the main thread); every other call is main-thread, and every listener and callback is delivered on the main thread. Called from another thread, a call stops a debuggable build and does nothing in a release build (show throws CannotShowNow). Times are milliseconds; prices are CPM. The package is so.kontext.video; Configuration, Content, User and Regulatory are nested in KontextVideo.

KontextVideo

The entry point, one object: KontextVideo.
method
Starts the SDK: stores the configuration and calls the server in the background. Call it once, in Application.onCreate; later calls are ignored. listener is optional and is told the resulting State on the main thread once the server answered or failed.
suspend method
Waits until the server answered or failed and returns the State; at once when it already has: Enabled, Disabled(reason) (the server switched the SDK off for this launch) or Failed (the server could not be reached; the next ads request tries again first).
State
The current state; also NotInitialized before initialize and Initializing while the server is asked.
User?
What you know about the viewer. Set it whenever you learn it; the next ads request carries it.
Regulatory?
Privacy and consent signals. The SDK reads the IAB values your consent platform writes to the default SharedPreferences; set here what it did not write (COPPA always comes from you).
String?
Selects which type of ad to render, for A/B tests agreed with Kontext.
String
The SDK’s version, as sent with every request. For your logs and crash reports.

KontextVideo.Configuration

Built as KontextVideo.Configuration("…") { logLevel = … }.
String
required
Identifies the publisher. Not a secret. You get a {publisher}-dev token for testing and a production one.
LogLevel
How much the SDK prints to Logcat, tag KontextVideo: NONE, ERROR, WARNING (default), INFO, DEBUG.
String
The ad server, by default the production one. Change it only for testing against a server Kontext gives you.

KontextVideo.Content

The video the ads are for. Everything beyond id and language is contextual signal. Built as KontextVideo.Content(id, language) { title = … }.
String
required
Your own id of the video, any scheme.
String
required
BCP-47, for example "en" or "pt-BR".
Rating?
SAFE or EXPLICIT. Leave unset when you don’t know; explicit content gets no ads that require safe content.
String?
The episode’s public page.
String?
List<String>?
IAB Content Taxonomy 3.0 ids.
String?
Long?
Milliseconds.
Int?
List<String>?
String?
For example "romance".
Content.Series?
Content.Series(id) { title = …; episodeCount = … }.

KontextVideo.User

Built as KontextVideo.User { id = … }.
String?
Your own unique identifier of the viewer.
String?
Plain email address, when consent allows it. Sent as given; the server hashes it on arrival and never stores the plain address.
String?
SHA-256 of the normalized address (trimmed, lowercased, UTF-8), 64 lowercase hex characters. Sent as given.
List<String>?
The viewer’s interests, in your own words.

KontextVideo.Regulatory

Built as KontextVideo.Regulatory { coppa = true }.
Boolean?
Whether the request is subject to GDPR.
IAB TCF v2 consent string.
Boolean?
Whether the request is subject to COPPA. Cannot be read from the device. When true, requests carry no advertising ID, no user ID, email or email hash; set it per viewer in an app for adults and children (after an age gate, or for a kids’ profile).
String?
IAB Global Privacy Platform string.
List<Int>?
GPP section ids that apply.
String?
Legacy IAB US Privacy (CCPA) string.

AdFormat

OVERLAY, PAUSE, LINEAR.

VideoAds

The ads of one video. Create one per episode; creating it sends nothing. Any number can be alive at once. Call destroy() when the viewer leaves the video: dropping the reference does not end its ads.
constructor
labels is optional: key-values that say where these ads play, such as the viewer’s stage in the series or the player’s layout. Every request of this VideoAds carries them, and your setup on our side decides what they change, such as which formats are offered. They are fixed for the object’s life and describe the screen, never the viewer. They are a free format, sent exactly as given: use the names and values Kontext gives you.
suspend method
The ad for one format: the same VideoAd as last time while it is unshown and valid, a new one otherwise. Calls made while a request runs share it. A failed request returns the held ad when it is still valid.Throws NoFill, Request (its failure says why), Destroyed, Disabled, NotInitialized, InitializationFailed. A cancelled coroutine stops waiting; the request itself continues.
method
The same for code without coroutines: callback is a VideoAdCallback and gets onAd(ad) or onError(error) on the main thread.
method
The player this episode plays in: a Media3 Player (import so.kontext.video.media3.track, from so.kontext:video-media3), or any ContentPlayer. The SDK reads its time for requests and events, and follows its playback for an overlay and a pause ad: an overlay shows over playing content only, and ends with onAdEnded(INTERRUPTED) when the content pauses, ends, or the player moves to another item; a pause ad ends with onAdEnded(INTERRUPTED) when the content plays again after a pause, wherever the viewer resumed it (the media notification, the lock screen, a headset, picture-in-picture). It ends this way only after the content was seen paused while the ad was on screen: a pause ad shown over playing content stays until the content pauses and plays again, and an overlay shown right after the content resumes ends the pause ad and shows. Held until destroy() or the next track; the Media3 adapter holds your player weakly. Call it when this episode starts playing in the player. Without a player, events carry 0 (right for a prefetch), an overlay runs on its own time and a pause ad stays until it is dismissed or closed. An overlay shown with no player tracked logs a warning: its duration then counts on-screen time, not video time. The first track while an overlay is on screen keeps it; tracking a different player ends it with onAdEnded(INTERRUPTED). Show an episode’s ads only in that episode: once another VideoAds tracks the same player, or the player plays another item than at track, this one’s overlay and pause ads throw Invalidated(ContentChanged) at show. Linear ads are not checked.
method
Releases the video’s ads. Every held ad is dropped and the advertiser told it was not used; the ad on screen ends with onAdEnded(DESTROYED); a format() or load() in flight throws Destroyed. Idempotent.Call it with whatever owns the VideoAds. A ViewModel: in onCleared(), and in every new Activity track its player and set the ads’ listeners again, so the ads survive a rotation. An Activity, a Fragment or a Compose DisposableEffect: in its onDestroy() (onDispose), every time, with android:configChanges declared for rotation so a rotation does not recreate it. A VideoAds nobody destroys is freed once nothing holds it (a player it tracks holds it while that player lives); its ad on screen then runs until it ends. Only destroy() ends its ads at once.
Content
What it was created with.
Boolean
true after destroy().
String?
The id of the latest ads request, null before the first. Quote it to Kontext when an ad or a no-fill looks wrong.

ContentPlayer

What the SDK reads from a player that is not a Media3 Player. Implement it, in a small adapter around your player, and pass it to track(player). The SDK reads it on the main thread.
Long
Where the content is, in milliseconds of the episode.
Boolean
false when the viewer or your app paused the content, or it ended. Buffering and seeking count as playing.
Float?
Optional. The playback speed, 1 being normal, when your player knows it. null (the default) allows up to about 4×.
method
Optional. Tell the ContentPlayer.Listener what the player does, as it happens, so an overlay reacts at once: onIsPlayingChanged(isPlaying), onSeek(), onContentChanged() (another item, or this one played to its end). Without a listener the SDK reads isPlaying four times a second while an overlay or pause ad is on screen, and at every show, and estimates seeks from the position.
Any?
Optional. What the player plays now, any value that stands for this play of the episode (your item, its id), compared with equals; null (the default) when the player cannot tell. Give a new value for another episode, and for a loop’s next play. Once it differs from the value at track, this VideoAds’s overlay and pause ads throw Invalidated(ContentChanged) at show, and one on screen ends with onAdEnded(INTERRUPTED) at the SDK’s next read. A null read is never a change.
An overlay’s duration counts milliseconds of video. Without onSeek() and playbackSpeed, the SDK treats a jump faster than about 4× real time as a seek and counts nothing for it. The Media3 adapter reports all of it.

VideoAd

One ad, from the server’s answer to the end of its presentation. Look at its facts, then load() or reject(), then show(), then exactly one onAdEnded. Shown at most once.

Facts

String
AdFormat
VideoAd.Price
Long?
Overlay: how long the SDK keeps it on screen, counting only time it is seen; null when it stays until ended. Linear: the video’s length. Always null for a pause ad.

State

Boolean
load() finished.
Boolean
Loaded, not shown, not rejected, not expired, and the SDK not switched off by the server: show() can be tried. A hint, not a guarantee; show() still measures the container.
InvalidationReason?
Why the ad ended before it was shown, once it did: Expired, Rejected, Destroyed, ContentChanged (its episode no longer plays in the tracked player), CreativeFailed(code).
Boolean
true from a successful show() on.
Boolean
true once the ad began to end. onAdEnded follows at once for an overlay or pause ad, and once its screen is gone for a linear ad.
Boolean
Whether the creative ran to its end: a video reached complete, an overlay’s duration elapsed. Separate from how it left the screen.
VideoAdListener?
Receives the ad’s moments. Held until onAdEnded has run, then let go.

Methods

suspend method
Renders the creative off screen and returns once it is ready, so show() is instant. Throws CreativeFailed, Invalidated, Destroyed, Disabled. A second call waits for the first. load(callback) is the same for code without coroutines: a VideoAdCallback.
method
You won’t use the ad; the server tells the advertiser. RejectReason.NotUsed (default) or RejectReason.Outbid(winningPrice, winner). Works until show(), loaded or not. Never throws: on an ad that was shown or already ended (expired, rejected, destroyed, failed) it does nothing and logs a line.
method
Shows an overlay or pause ad inside container, the ViewGroup the content plays in. Returning means the ad is on screen, or your own code that ran during the call already ended it: onAdEnded arrived and hasEnded is true. The ad follows the container when it resizes or rotates; a container still too small for it half a second later ends the ad with onAdEnded(INTERRUPTED). The container must lay the ad over the content, as a FrameLayout does. Throws, with nothing shown: NotLoaded, AlreadyShown, AnotherAdShowing, Invalidated, Destroyed, Disabled, CannotShowNow (the container is not attached to a window, not shown, has no area, or is not on screen in its window, such as a pager’s neighbour page: show on the current page only; its Activity is stopped, finishing, destroyed or in picture-in-picture, or the app is in the background; or the container refuses a child or recycles its children, such as a ScrollView that already has one, a ListView or a RecyclerView), ContainerTooSmall (its padding and your insets count against the space) and ContentPaused (an overlay over paused content; the ad stays ready in these three), WrongShowMethod (a linear ad). With a player given to track, an overlay also ends with onAdEnded(INTERRUPTED) when the content stops, and a pause ad when the content plays again. When nothing of the ad can be seen where it is placed (clipped away by an ancestor, for example), show returns and the ad ends at once with onAdEnded(INTERRUPTED), before any impression. A show of this same ad made by your own code during the call (the onAdEnded of an ad it ended showing this one) counts as this call’s: it returns normally.
method
Shows a linear ad full screen, in the SDK’s own Activity started from activity. Back does nothing there: the creative’s own controls end the ad. Throws, with nothing shown: the errors above, CannotShowNow for an Activity that is stopped, finishing, destroyed or in picture-in-picture (the ad stays ready; try again once it is visible), WrongShowMethod (an overlay or pause ad). A started Activity that is not resumed yet is fine: onStart, an Activity Result or permission callback, onNewIntent. An Activity with launchMode="singleInstance" is not supported (the ad opens in another task, and the viewer returns there): use standard, singleTop or singleTask. A show of this same ad made by your own code during the call returns normally.
method
Ends an overlay or pause ad because you say so; onAdEnded(DISMISSED) follows, synchronously. Before show() and after the end it does nothing. Never throws. A linear ad ends by itself or by the viewer: dismiss() on one stops a debuggable build and does nothing in a release build.
Kotlin does not make you catch exceptions, but show throws for routine outcomes (the ad expired, another ad is showing): wrap every show in a try.

VideoAdListener

Delivered on the main thread. Every method has an empty default; implement the ones you need. Nothing is delivered before show(). After it: the impression and clicks, in no fixed order, then exactly one onAdEnded, always last. Every method gets the ad first, so one listener can serve several ads.
method
The impression was counted: at show() for an image or HTML creative, at the first frame for a video. At most once; may not come at all, when the ad ends before.
method
The viewer tapped the ad. The SDK recorded the click and started opening its target. Delivered as the opening starts, so whether anything opened, and which, is not reported. Once per tap. A web link no installed app claims opens in an in-app browser (a Custom Tab) over your app, so the viewer stays in it; without a Custom Tabs browser it opens in the default browser. Play Store links, an app’s own links and web links an installed app claims (verified App Links) open that app. Under its own in-app browser the ad stays: an overlay or pause ad is not ended, its time on screen and viewability wait for the viewer’s return, and a linear ad’s video pauses and plays on after.Web links, store links and app deep links open, links into your own app included. System actions (tel:, sms: and the like) are refused; the ad’s fallback web link opens instead when it has one.
method
The ad broke after show() returned. onAdEnded(FAILED) follows.
method
Presentation is over. Exactly once per successful show(), always last. Resume your content here, deciding from the format and reason. For an overlay or pause ad it comes synchronously, even from inside your own dismiss() or destroy(). For a linear ad it comes once the ad’s screen is gone, so you can start your next screen from it.

VideoAd.EndReason

VideoAdException

Thrown by format(), load() or show() (reject() and dismiss() never throw): a thrown exception means nothing happened on screen and nothing was fired, except a failed load()’s VAST error event. Two are also delivered through onAdFailed after a show() that succeeded: CreativeFailed and CannotShowNow; the ad is over then. Every one is a subclass of VideoAdException.

VideoAdException.NoFillReason