Server Side Ad Insertion using FLBrightcove

The fl-player-ads-brightcove library enables the playback of Brightcove-curated streams with advertisements. To build a Brightcove player, use the BrightcoveAdsPlayerBuilder() API with the following property's:

Property	Type	Description
vmapURL	String	Sets the URL to remote VMAP document that contains ads cue point metadata.
adPlaybackPolicy	AdPlaybackPolicy	Sets the [AdPlaybackPolicy] instance that specifies the policy rules for Brightcove ads handling.
playbackPolicyHandler	PlaybackPolicyHandler	Sets the [PlaybackPolicyHandler] instance that enforces the policy rules related to the content with Brightcove ads.
playbackPolicyHandlerListener	PlaybackPolicyHandler.Listener	Sets the [PlaybackPolicyHandler.Listener] instance that provides the notification for ad playback policy related events.
palConfiguration	PALConfiguration	Sets the [PALConfiguration] instance that is used in the [PALSession] initialization. Optionally sets the permission to store user data like cookies, device IDs, and advertising IDs when using [PALSession] calls.
allowPALSessionDataStorage	Boolean	If the value is [Boolean.true] the user gives the consent to store data.The default value is [Boolean.false] - no consent.

note

The client application may optionally provide custom AdPlaybackPolicy, and PlaybackPolicyHandler implementation, and also PALConfiguration instance as BrightcoveAdsPlayerBuilder properties.

Brightcove Player Creation Use Cases

The following use cases are supported by BrightcoveAdsPlayerBuilder forBrightcovePlayer instance creation:

1. The application provides VMAP URL and PAL configuration and optionally other builder properties but not media URL.
2. The application provides VMAP URL and optionally other builder properties but not PAL configuration and media URL.
3. The application provides media URL and PAL configuration and optionally other builder properties but not VMAP URL.
4. The application provides media URL and optionally other builder properties but not VMAP URL and PAL configuration.

Create Brightcove Player

A Player should be built using BrightcoveAdsPlayerBuilder as an extension of PlayerBuilder (see Brightcove Player Creation Use Cases section).

import android.content.Context
import com.quickplay.vstb7.player.model.MediaType
val brightcovePlayerBuilder = BrightcoveAdsPlayerBuilder()
brightcovePlayerBuilder.mediaType(MediaType.HLS)
brightcovePlayerBuilder.vmapURL(vmapURL)
brightcovePlayerBuilder.playbackPolicyHandlerListener(policyHandlerListener)
val context: Context = getApplication()
coroutineScope.launch {
    when (val result: Result<BrightcovePlayer?, Error?> =
        brightcovePlayerBuilder.buildAsync(
            context
        )
    ) {
        is Result.Success -> {
            val brightcovePlayer = result.value
            brightcovePlayer?.let { adsPlayer ->
                adsPlayer.addListener(playerListener)
                adsPlayer.addAuxiliaryListener(playerAuxiliaryListener)
                adsPlayer.registerAdListener(adListener)
                bookmarkPositionMs?.let { bookmark ->
                    adsPlayer.playbackProperties.initialStartTimeMs = bookmark
                }
                adsPlayer.play()
            }
        }
        is Result.Failure -> {// If the `BrightcoveAdsPlayerBuilder.buildAsync(context)` invocation fails with an `Error` this condition, most likely, is the result of the VMAP file download or parsing failure.
           // handle error
        }
    }
}

note

NOTE that the PlayerBuilder build function is deprecated and MUST not be used and only buildAsync should be used. This function is declared assuspendfunction and MUST be called using CoroutineScope builder function e.g. using launch extension function.

Once the BrightcovePlayer instance is built successfully the client application may optionally retrieve the preview image files metadata, if available, using thumbnails property of the BrightcovePlayer instance. If the client application logic decides to use the preview image files metadata directly then it is responsible for downloading and decoding the preview images based on the current player playhead position. BrightcovePlayer provides another API to retrieve a preview image URL for a given player playhead position - getThumbnailUrl(positionMs: Long).

player?.getThumbnailPreview(position) { preview ->
   logger.trace { "Got thumbnail bitmap: $preview" }
}

Listening to Ad Events

You can register AdEventListener instance with AdComposedPlayer for listening to Ad Events. The following ad events are triggered by AdEventListener callbacks:

1. Cue Point availability (available only after obtaining a response from Ad Server)
2. Ad Break Start called when the first Ad, in an Ad Break, have started playing. This event may also provide AdBreakInfo metadata for the active Ad Break.
3. Ad Start called when an Ad has started playing. This event will also provide AdInfo metadata for the active Ad.
4. Ad Playback Progress called during Ad Break playback when the Ad's progress is updated. This event will also provide AdProgressInfo metadata for the active Ad Break.
5. Ad End called when an Ad has finished playing. This event will also provide AdInfo metadata for the active Ad.
6. Ad Break End called when all the Ads, in an Ad Break, have finished playing. This event may also provide AdBreakInfo metadata for the active Ad Break.
7. Ad Error called when an error has been encountered during Ads playback. This event will also provide Error metadata for the active Ad.
8. Ad Tracking Event called when an ad tracking event sucha as ad's first quartile, midpoint, third quartile etc. is triggered. This event will also provide AdTrackingEvent metadata for the active Ad Break or Ad.

val adEventListener = object : AdEventListener {
      override fun onAdCuePointsAvailable(cuePoints: LongArray) {
        logger.info { "cue_points_available" }
      }
      override fun onAdBreakStart(adBreakInfo: AdBreakInfo?) {
        logger.info { "ad_break_start" }
      }
      override fun onAdStart(adInfo: AdInfo) {
        logger.info { "ad_start" }
      }
      override fun onAdPlaybackProgress(adProgresInfo: AdProgressInfo) {
        logger.info { "ad_progress" }
      }
      override fun onAdEnd(adInfo: AdInfo) {
        logger.info { "ad_end" }
      }
      override fun onAdBreakEnd(adBreakInfo: AdBreakInfo?) {
        logger.info { "ad_break_end" }
      }
    }
adsPlayer.registerAdListener(adEventListener)

Ad Metadata

AdInfo

Represents an advert object.

Property	Type	Description
adID	string	The identifier of the advert
sequence	number	The sequence of the advert
adStartTimeOffsetMs	number	The start playhead position of the advert in milliseconds
durationMs	number	The duration of the advert in milliseconds
remainingTimeMs	number	Returns the natural playback time remaining for the advert in milliseconds
isSkippable	boolean	Indicates if the ad is skippable
skipOffsetMs	number	The value of skip offset for the advert, in milliseconds. If the VAST skip offset is not defined then this method returns -1, signifying that the advert cannot be skipped.
isFiller	boolean	Whether this advert represents filler content
adBreakInfo	AdBreakInfo	The ad break in which the advert belongs in
adVastProperties	AdVastProperties	Represents a VAST properties of this advert.

AdBreakInfo

Represents an ad break object.

Property	Type	Description
adBreakID	String	Unique id of the ad break
contentTimePosition	AdContentTimePosition	The position of the ad break, can be on of preroll, midroll or postroll
adSequencePosition	Int	The sequence position of the ad within the ad break.
adBreakStartTimeOffsetMs	Double	The content time offset at which the current ad break was scheduled
remainingTimeMs	Double	The natural playback time remaining for the ad break in milliseconds
durationMs	Double	The maximum duration of the ad break in milliseconds.
totalAds	Int	The total number of ads contained within this ad break.
adBreakIndex	Int	The index of the current ad break

note

The totalAds read from AdPlayer may not be accurate when it comes from onAdStart event. This may change once ad playback starts. GoogleIMA advises to read totalAds on or after FIRST_QUARTILE ad tracking event, to get a reliable data.