Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Obtaining AdPlayerTag Instance

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

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

Kotlin

Code Block
languagekotlin
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
languagejava
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
languagekotlin
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
languagejava
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
languagekotlin
AdPlayer.getTagNowOrNull(tagId)?.let { tag -> 
  // do action
}

Java

Code Block
languagejava
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
languagekotlin
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
languagejava
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 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

Code Block
languagekotlin
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
languagejava
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
languagekotlin
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
languagekotlin
coroutineScope.launch { 
    tag.eventsFlow.collectLatest { event: AdPlayerEvent ->
        when (event) { 
            // handle events
        }
    }
}

Or add a listener to an instance of AdPlayerTag

Code Block
languagekotlin
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
languagejava
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
languagejava
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
languagejava
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 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

Code Block
languagekotlin
tag.playingStateListener = object : AdPlayerPlayingStateListener {
    override fun onStateChanged(newState: AdPlayerPlayingState) {
        // handle state change
    }
}

Or observe the StateFlow of the player state

Code Block
languagekotlin
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
languagejava
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 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.