JioAds CSAI

The fl-android-ads-jio library integrates with JioAds to offer Client Side Ad Insertion capability for VOD.

Jio Ads

The fl-android-ads-jio library integrates the JioAds SDK to offer Client Side Ad Insertion for VOD using the VMAP for VOD API. JioAds manages the pre-roll, mid-roll and post-roll ad breaks defined in the VMAP document, while the content player is paused and resumed around each ad break.

Supported JioAds SDK version: 2.2.10-media3

Add the dependencies

The JioAds SDK is hosted in the Firstlight JFrog 3rd-party repository, which is not part of the repositories configured in the setup guide. Add it with the same JFrog credentials (jFrogUser and jFrogPassword in gradle.properties) used for the Quickplay SDK repositories.

// application level build.gradle
allprojects {
  repositories {
    ....
    maven {
      url "https://firstlight.jfrog.io/artifactory/3rd-party"
      credentials {
        username = "${rootProject.jFrogUser}"
        password = "${rootProject.jFrogPassword}"
      }
    }
  }
}

// module level build.gradle
implementation 'content.com.jio:jio-ads-android:2.2.10-media3'
implementation 'com.quickplay.vstb7:fl-player-ads-jio:<QP-SDK-Versions>'

note

Make sure that the version of the JioAds SDK is compatible with the Quickplay libraries that you're using.

Initialize the JioAds SDK

Initialize the SDK once, before creating the ads player, for example in Application.onCreate.

JioAdsPlayerFactory.init(applicationContext)

Call JioAdsPlayerFactory.release() when the SDK is no longer needed, for example when the main Activity is destroyed. It shuts down the SDK's internal executor and clears its cached state. init() must be called again before creating a new ads player after release().

Create the ad request

val adRequest = JioVmapVodAdsRequest(
  adTagUrl = "<VMAP document URL>",
  prerollCid = "pre-roll",
  midrollCid = "mid-roll",
  postrollCid = "post-roll",
  thresholdMs = 1000
)

Property	Description
adTagUrl	The VMAP document URL to be resolved and played. A null or blank value makes the build fail with an error.
prerollCid/midrollCid/postrollCid	Cid per ad break position.
customMetadata	Optional custom key/value targeting metadata.
languageTag	Optional IETF BCP 47 language tag used for ad related labels.
adOverlayUIScopes	Optional views on top of the ad view excluded from ad viewability measurement.
thresholdMs	Optional threshold, in milliseconds, ahead of an ad break at which JioAds starts preparing it.
loadMediaTimeoutMs	Optional time, in milliseconds, to wait for the first ad break before content playback starts anyway. Defaults to 15000.

Create ad composed player

JioCSAIAdsPlayerBuilder builds the content player, creates the JioAds loader and ad container using the host Activity, and triggers the VMAP request. Use the returned JioAdsPlayer (an AdComposedPlayer) in place of the content player.

val result = JioCSAIAdsPlayerBuilder()
  .mediaURL("<content URL>")
  .mediaType(MediaType.DASH)
  .build(applicationContext, adRequest, activity)

when (result) {
  is Result.Success -> adsPlayer = result.value // JioAdsPlayer
  is Result.Failure -> handleError(result.value) // com.quickplay.vstb7.error.Error
}

Listen to ad events

Register an AdEventListener to receive ad break and ad events. The listener contract is the same as other CSAI integration.

val adEventListener = object : AdEventListener {
  override fun onAdBreakStart(adBreakInfo: AdBreakInfo?) { }
  override fun onAdStart(adInfo: AdInfo) { }
  override fun onAdPlaybackProgress(adProgressInfo: AdProgressInfo) { }
  override fun onAdEnd(adInfo: AdInfo) { }
  override fun onAdBreakEnd(adBreakInfo: AdBreakInfo?) { }
  override fun onAdError(error: Error) { }
}
adsPlayer.registerAdListener(adEventListener)

Start playback

adsPlayer.load()
adsPlayer.play()

If play() is called before the first ad break is ready, content is only loaded and playback is held until the pre-roll starts, fails or times out. While an ad is loading or playing, the player state reflects the ad. Register a Player.Listener on adsPlayer as usual to observe state changes.

Release

adsPlayer.unregisterAdListener(adEventListener)
adsPlayer.stop()