Obtaining AdPlayerTag Instance

Instances of AdPlayerTag can be obtained in one of two ways:

Obtaining them right after the initialization (this is the earliest point at which the instance is available)

Kotlin

AdPlayer.initializePublisher(publisherId) {
    // initialize tags here
}
// this is optional
.onTagReady { tag: AdPlayerTag ->
    // tag instance available here
}
// this is optional
.onError { error: AdPlayerError ->
    // tag initialization failed
}

Java

AdPlayer.initializePublisher(publisher, new AdPlayerTagInitCallback() {
	@Override
	public void onTagReady(@NonNull AdPlayerTag adPlayerTag) {
		// tag instance available here
	}

	@Override
	public void onError(@NonNull AdPlayerError adPlayerError) {
		// tag initialization failed
	}
});

2. Requesting them from AdPlayer

Kotlin

coroutineScope.launch {
    AdPlayer.getTagWhenReady(tagId)
        .onSuccess { tag: AdPlayerTag ->
          // tag instance available here
        }.onFailure { error: AdPlayerError ->
          // tag initialization failed
        }
}

If you wish to avoid using Coroutines, a listener may also be used just like in the Java sample.

Java

3. In order to perform an action only if a tag is ready now and otherwise skip it, you may request the tag now if present using the following API

Kotlin

Java

A common use for this API is when launching interstitial ads.

Basic Parameters

Parameter Name	Parameter Type	Parameter Description

Parameter Name	Parameter Type	Parameter Description
id	String	A unique identifier of the AdPlayerTag as provided in the initialization request and as appears in the dashboard.
publisherId	String	The unique identifier of the tags publisher as provided in the initialization request and as appears in the dashboard.

Controls

The AdPlayerTag allows you to control the player programmatically.

Playback

To pause the player, call AdPlayerTag.pause().
To resume playback, call AdPlayerTag.resume().
To skip an ad if one is playing and skippable, call AdPlayerTag.skipAd().
When using playlist content from our CMS, use the following to control which content is being played:
- AdPlayerTag.nextContent()
- AdPlayerTag.previousContent()
- AdPlayerTag.setContentByIndex(index: Int)
To detect whether or not the player is playing query AdPlayerTag.playingState.value.isPlaying.
To be notified about changes in the state of the player, observe it in the following way.

Kotlin

The state is a sealed class and is one of:

AdPlayerPlayingState.Initial, AdPlayerPlayingState.Playing, AdPlayerPlayingState.NotPlaying, AdPlayerPlayingState.Display.

If you wish to avoid using Coroutines, a listener may also be used just like in the Java sample.

Java

Display

To detect the displaying mode of the player, use AdPlayerTag.playingState.value.displayMode.
The supported display modes are:

Display Mode	Description

Display Mode	Description
Not Displayed	The player is not being displayed on the screen.
Inread	The player is being displayed in a `AdPlayerPlacementView` inside the application’s UI. This is the default display mode.
Full Screen	The player is taking up the entire screen.
Floating	The player is occupying a part of the screen above the content.

To move between Inread and Full Screen display modes, use the following methods:
- AdPlayerTag.toggleFullScreen()
- AdPlayerTag.enterFullScreen()
- AdPlayerTag.exitFullScreen()
The transition to and from the Floating display mode is performed automatically.

Configurations

While most of the configurations are available on the dashboard, the AdPlayerTag provides some configurations to the player that can be changed in code. The configurations should be provided as part of the initialization process.

Kotlin

Java

Events

As the player is playing its content, the AdPlayerTag emits relevant events describing the process.

To receive the events you should follow one of the following methods:

Kotlin

Add a listener as part of the tag initialization process

Or observe a Flow of events on an instance of AdPlayerTag

Or add a listener to an instance of AdPlayerTag

Java

Add a listener as part of the tag initialization process

Or add a listener to an instance of AdPlayerTag

Note that some events contain parameters. To obtain the parameters the event must be cast to its class

The emitted events are:

Event class	Event type	Description

Event class	Event type	Description
AdPlayerEvent.FullScreenRequest()	AdPlayerEventType.FULL_SCREEN_REQUESTED	Called when the user requested full screen.
AdPlayerEvent.Inventory()	AdPlayerEventType.INVENTORY	Called when the player is initialized.
AdPlayerEvent.AdSourceLoaded()	AdPlayerEventType.AD_SOURCE_LOADED	Indicates the first time an ad sources triggered the AdLoaded event.
AdPlayerEvent.AdImpression()	AdPlayerEventType.AD_IMPRESSION	Called when there is a video impression.
AdPlayerEvent.AdVideoFirstQuartile()	AdPlayerEventType.AD_VIDEO_FIRST_QUARTILE	Called when the ad reached 25% of the ad video.
AdPlayerEvent.AdVideoMidpoint()	AdPlayerEventType.AD_VIDEO_MIDPOINT	Called when the ad reached 50% of the ad video.
AdPlayerEvent.AdVideoThirdQuartile()	AdPlayerEventType.AD_VIDEO_THIRD_QUARTILE	Called when the ad reached 75% of the ad video.
AdPlayerEvent.AdVideoComplete()	AdPlayerEventType.AD_VIDEO_COMPLETE	Called when the ad is completed.
AdPlayerEvent.AdClickThrough()	AdPlayerEventType.AD_CLICK_THROUGH	Called when the ad is clicked on.
AdPlayerEvent.AdSkipped()	AdPlayerEventType.AD_SKIPPED	Called when an ad is skipped.
AdPlayerEvent.AdSkippableStateChange()	AdPlayerEventType.AD_SKIPPABLE_STATE_CHANGE	Called when the ad skip button becomes available.
AdPlayerEvent.Closed()	AdPlayerEventType.CLOSED	Called when the close button is clicked.
AdPlayerEvent.AdPaused()	AdPlayerEventType.AD_PAUSED	Called when the ad is paused.
AdPlayerEvent.AdPlaying()	AdPlayerEventType.AD_PLAYING	Called when the ad starts playing or resumed.
AdPlayerEvent.ContentPaused()	AdPlayerEventType.CONTENT_PAUSED	Called when the content video is paused.
AdPlayerEvent.ContentPlaying()	AdPlayerEventType.CONTENT_PLAYING	Called when the content video resume playing.
AdPlayerEvent.AdVolumeChange(val volume: Float)	AdPlayerEventType.AD_VOLUME_CHANGE	Called when the ad volume is changed. Contains the new volume level in the `AdVolumeChange.volume` parameter.
AdPlayerEvent.ContentVolumeChange(val volume: Float)	AdPlayerEventType.CONTENT_VOLUME_CHANGE	Called when the content volume is changed. Contains the new volume level in the `ContentVolumeChange.volume` parameter.
AdPlayerEvent.ContentVideoStart()	AdPlayerEventType.CONTENT_VIDEO_START	Content started playing.
AdPlayerEvent.ContentVideoFirstQuartile()	AdPlayerEventType.CONTENT_VIDEO_FIRST_QUARTILE	Called when the content reached 25%.
AdPlayerEvent.ContentVideoMidpoint()	AdPlayerEventType.CONTENT_VIDEO_MIDPOINT	Called when the content reached 50%.
AdPlayerEvent.ContentVideoThirdQuartile()	AdPlayerEventType.CONTENT_VIDEO_THIRD_QUARTILE	Called when the content reached 75%.
AdPlayerEvent.ContentVideoComplete()	AdPlayerEventType.CONTENT_VIDEO_COMPLETE	Called when the content is completed.
AdPlayerEvent.AdError(val message: String?)	AdPlayerEventType.AD_ERROR	Called by the player every time it finish running 1 + vastRetry waterfall runs without impression. An (optional) error message can be found at `AdError.message`.
AdPlayerEvent.AdErrorLimit()	AdPlayerEventType.AD_ERROR_LIMIT	Called also whenever the player decides that it should stop running, for example when maxImp or maxRun is reached, to indicate the player is stopping calls for ads.
AdPlayerEvent.Error(val message: String?)	AdPlayerEventType.ERROR	An error has occurred. An (optional) error message can be found at `Error.message`.

Playback State

The AdPlayer is exposing its playback state at all times. To observe the playback state you should provide the appropriate listener:

Kotlin

Add a state listener

Or observe the StateFlow of the player state

The state is a sealed class and is one of:

AdPlayerPlayingState.Initial, AdPlayerPlayingState.Playing, AdPlayerPlayingState.NotPlaying, AdPlayerPlayingState.Display.

Java

Add a state listener

The state holds the following information and will update on any change of these parameters:

Parameter Name	Parameter Type	Parameter Description

Parameter Name	Parameter Type	Parameter Description
isPlaying	Boolean	is `true` if the player is currently playing video.
isAd	Boolean	is `true` if the player is displaying an ad. May be `true` if `isPlaying` is `false` in case an ad is displayed but paused.
displayMode	AdPlayerDisplayMode	the mode in which the player is currently displayed. See “Display” section above.

Help

AdPlayerTag APIs - Android

Obtaining AdPlayerTag Instance

Basic Parameters

Controls

Playback

Display

Configurations

Events

Playback State