About

AdPlayerTag provides ability to control the player. It can be received in any of the ways below.

• as a callback during initialization:

AdPlayer.initializePublisher("publisherId") { TODO() }
    .onTagReady { tag: AdPlayerTag ->
        // tag instance available here
    }
    .onError { error: AdPlayerError ->
        // tag initialization failed
    }

• registering a callback anywhere:

AdPlayer.getTagWhenReady("tagId", object  : AdPlayerTagInitCallback {
    override fun onTagReady(tag: AdPlayerTag) {
        // tag instance available here
    }

    override fun onError(error: AdPlayerError, tagId: String?) {
        // tag initialization failed
    }
}

• using suspend functions:

when (val result = AdPlayer.getTagWhenReady("tagId")) {
    is AvResult.Success -> {
        val tag = result.value        // tag instance available here
    }
    is AvResult.Failure -> {
        val error = result.value      // tag initialization failed
    }
}

• non-blocking peeking functions:

val tag = AdPlayer.getTagNowOrNull("tagId")
if (tag != null) {
    // tag instance available here
}

Tag Configuration

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.

AdPlayer.initializePublisher("publisherId") {
    addTag("tagId") {
        // tag configuration happens here
        label = "tag_label"
        backgroundColor = Color.BLACK
        macros = mutableListOf(
            AdPlayerMacro.CmsId("cmsId"),
            AdPlayerMacro.PlaylistId("playlistId"),
            AdPlayerMacro.Custom("customKey", "customValue"),
        )
    }
}

Regulations

Global Privacy Platform (GPP)

Library will track GPP related values mentioned in Global Privacy Platform.

Following values will be taken from the SharedPreferences automatically:

IABGPP_HDR_GppString
IABGPP_GppSID

General Data Protection Regulation (GDPR)

Library will track GDPR related values mentioned in GDPR Transparency and Consent Framework.

Following values will be taken from the SharedPreferences automatically:

IABTCF_gdprApplies
IABTCF_TCString

This code can be used in case application wants to override default behaviour:

AdPlayer.setGdprRequired(true)
AdPlayer.setGdprConsentString("...")

Tag Controls

The AdPlayerTag allows you to control the player programmatically.

Playback

• AdPlayerTag.pause() - pauses the player
• AdPlayerTag.resume() - resumes the player
• AdPlayerTag.skipAd() - skips an ad if one is playing and skippable
• AdPlayerTag.playingState.value.isPlaying - detects whether or not the player is playing

Playlist

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)

Overriding in-stream content during initialization

In-stream content can be overriden during initialization with custom content:

AdPlayer.initializePublisher("publisherId") {
    addTag("tagId") {
        instreamContentOverride = InstreamContent(
            cmsType = "video",
            cmsId = "cmsId",
        )
    }
}

Changing in-stream content on-demand

In-stream content can be replaced with some custom content:

val tag: AdPlayerTag = TODO()
val configItem: JSONObject = TODO()

tag.preloadVideoAsync()
tag.updateContentList(JSONArray().also { it.put(configItem) })

Alternatively items in the content playlist can be inserted or removed:

val tag: AdPlayerTag = TODO()
val configItem: JSONObject = TODO()

tag.preloadVideoAsync()
tag.addContentAt(5, configItem)
tag.removeContentAt(2)

Example of the config item:

{
  "url": "https://sample-videos.com/video321/mp4/720/big_buck_bunny_720p_1mb.mp4"
}

Display modes

AdPlayerTag.playingState.value.displayMode can be used to detect the displaying mode of the player. Currently these modes are supported:

• 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.

Player state

To be notified about changes in the state of the player, observe it in the following way:

tag.playingState.collect {
    when (it) {
        is AdPlayerPlayingState.Initial -> {}
        is AdPlayerPlayingState.Playing -> {
            if (it.isAd) {
                // the player is playing an ad
            } else {
                // the player is playing content
            }
        }
        is AdPlayerPlayingState.NotPlaying -> {}
        is AdPlayerPlayingState.Display -> {}
    }
}

Player events

To be notified about one-off events of the player, observe it in the following way:

tag.eventsFlow.collect {
    when (it) { 
        // handle events
    }
}