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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
AdPlayer.getTagWhenReady(tagId, new AdPlayerTagInitCallback() { @Override public void onTagReady(@NonNull AdPlayerTag tag) { // tag instance available here } @Override public void onError(@NonNull AdPlayerError error) { // tag initialization failed } }); |
3. If you would like 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
Code Block | ||
---|---|---|
| ||
AdPlayer.getTagNowOrNull(tagId)?.let { tag -> // do action } |
Java
Code Block | ||
---|---|---|
| ||
AdPlayerTag tag = AdPlayer.getTagNowOrNull(tagId); if (tag1 != null) { // do action } |
Info |
---|
A common use for this API is when launching interstitial ads. |
Basic Parameters
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
Code Block | ||
---|---|---|
| ||
coroutineScope.launch { tag.playingState.collectLatest { playingState: AdPlayerPlayingState -> when (playingState) { is AdPlayerPlayingState.Initial -> {} is AdPlayerPlayingState.Playing -> { if (playingState.isAd) { // the player is playing an ad } else { // the player is playing content } } is AdPlayerPlayingState.NotPlaying -> {} is AdPlayerPlayingState.Dsiplay -> {} } } } |
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
Code Block | ||
---|---|---|
| ||
tag.setPlayingStateListener(new AdPlayerPlayingStateListener() { @Override public void onStateChanged(@NonNull AdPlayerPlayingState newState) { if (newState.isPlaying()) { // the player is playing } else { // the player is not playing } if (newState.isAd()) { // the player is displaying an ad } else { // the player is not displaying an ad } } }); |
Display
To detect the displaying mode of the player, use
AdPlayerTag.playingState.value.displayMode
.The supported display modes are:
Display Mode | Description |
---|---|
Not Displayed | The player is not being displayed on the screen. |
Inread | The player is being displayed in a |
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
andFull 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
Code Block | ||
---|---|---|
| ||
AdPlayer.initializePublisher(publisherId) { addTag(tag1Id) { // configure your tag here label = "tag_label" backgroundColor = Color.BLACK macros = mutableListOf( AdPlayerMacro.CmsId(cmsId), AdPlayerMacro.PlaylistId(playlistId), AdPlayerMacro.Custom(customKey, customValue), ) } } |
Java
Code Block | ||
---|---|---|
| ||
AdPlayerTagConfiguration tag = new AdPlayerTagConfiguration(tag1Id); // configure your tag here tag.setLabel("tag_label"); tag.setBackgroundColor(Color.BLACK); List<AdPlayerMacro> macros = new ArrayList<>(); macros.add(new AdPlayerMacro.CmsId(cmsId)); macros.add(new AdPlayerMacro.PlaylistId(playlistId)); macros.add(new AdPlayerMacro.Custom(customKey, customValue)); tag.setMacros(macros); AdPlayerPublisherConfiguration publisher = new AdPlayerPublisherConfiguration(publisherId, tag); AdPlayer.initializePublisher(publisher); |
Some of the configurations also appear as assignable fields on the AdPlayerTag
and can be changed at any time while others can be provided only at initialization and cannot be changed later.
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
Code Block | ||
---|---|---|
| ||
AdPlayer.initializePublisher(publisherId) { addTag(tagId) { eventsListener { event: AdPlayerEvent -> when (event) { // handle events } } } } |
Or observe a Flow
of events on an instance of AdPlayerTag
Code Block | ||
---|---|---|
| ||
coroutineScope.launch { tag.eventsFlow.collectLatest { event: AdPlayerEvent -> when (event) { // handle events } } } |
Or add a listener to an instance of AdPlayerTag
Code Block | ||
---|---|---|
| ||
tag.eventsListener = object : AdPlayerTagEventsListener { override fun onAdPlayerEvent(event: AdPlayerEvent) { when (event) { // handle events } } } |
Java
Add a listener as part of the tag initialization process
Code Block | ||
---|---|---|
| ||
AdPlayerTagConfiguration tag = new AdPlayerTagConfiguration(tagId); // configure your tag here tag.setEventsListener(new AdPlayerTagEventsListener() { @Override public void onAdPlayerEvent(@NonNull AdPlayerEvent event) { switch (event.getType()) { // handle events } } }); |
Or add a listener to an instance of AdPlayerTag
Code Block | ||
---|---|---|
| ||
tag.setEventsListener(new AdPlayerTagEventsListener() { @Override public void onAdPlayerEvent(@NonNull AdPlayerEvent event) { switch (event.getType()) { // handle events } } }); |
Note that some events contain parameters. To obtain the parameters the event must be cast to its class
Code Block | ||
---|---|---|
| ||
switch (event.getType()) { case AD_VOLUME_CHANGE: float volume = ((AdPlayerEvent.AdVolumeChange) event).getVolume(); } |
The emitted events are:
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 |
AdPlayerEvent.ContentVolumeChange(val volume: Float) | AdPlayerEventType.CONTENT_VOLUME_CHANGE | Called when the content volume is changed. Contains the new volume level in the |
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 |
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 |
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
Code Block | ||
---|---|---|
| ||
tag.playingStateListener = object : AdPlayerPlayingStateListener { override fun onStateChanged(newState: AdPlayerPlayingState) { // handle state change } } |
Or observe the StateFlow
of the player state
Code Block | ||
---|---|---|
| ||
coroutineScope.launch { tag.playingState.collectLatest { playingState -> // handle state change } } |
The state is a sealed class and is one of:
AdPlayerPlayingState.Initial
, AdPlayerPlayingState.Playing
, AdPlayerPlayingState.NotPlaying
, AdPlayerPlayingState.Display
.
Java
Add a state listener
Code Block | ||
---|---|---|
| ||
tag.setPlayingStateListener(new AdPlayerPlayingStateListener() { @Override public void onStateChanged(@NonNull AdPlayerPlayingState adPlayerPlayingState) { // handle state change here } }); |
The state holds the following information and will update on any change of these parameters:
Parameter Name | Parameter Type | Parameter Description |
---|---|---|
isPlaying | Boolean | is |
isAd | Boolean | is |
displayMode | AdPlayerDisplayMode | the mode in which the player is currently displayed. See “Display” section above. |