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 properties:

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.
dataCollectionConfig	BrightcoveDataCollectionConfig	Enables Brightcove Data Collection API v2 reporting.

note

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

Brightcove player creation use cases

The following use cases are supported by BrightcoveAdsPlayerBuilder for BrightcovePlayer 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

Build a Player using BrightcoveAdsPlayerBuilder as an extension of PlayerBuilder (see the Brightcove Player Creation Use Cases section).

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

The PlayerBuilder build function is deprecated and MUST not be used. Only use buildAsync. This function is declared as a suspend function and MUST be called using a CoroutineScope builder function (for example, using the launch extension function).

Once you successfully build the BrightcovePlayer instance, you may optionally retrieve the preview image files metadata, if available, using the thumbnails property of the BrightcovePlayer instance. If you decide to use the preview image files metadata directly, you're 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" }
}

Brightcove Data Collection API v2

Brightcove requires clients who use a third-party player (instead of the Brightcove player) to report playback data via the Data Collection API v2. This integration satisfies that requirement while keeping the QuickPlay Player in place.

Automatically Tracked Events

#	Event	When
1	player_load	Session starts (startSession() called)
2	video_impression	Player state reaches LOADED
3	play_request	Player state reaches LOADING
4	video_view	First STARTED state outside an ad break
5	video_engagement	Periodically during playback (default every 10 s)
6	ad_mode_begin	Ad break begins
7	ad_mode_complete	Ad break ends
8	error	Playback error occurs

BrightcoveDataCollectionConfig Reference

Field	Required	Default	Description
accountId	Yes	—	Brightcove account ID
videoId	Yes	—	Brightcove video ID
videoName	No	—	Human-readable name of the video
sessionId	No	auto UUID	Per-session identifier
engagementEventInterval	No	10000	The interval (ms) between video_engagement beacons has an upper bound of 20000ms. If a higher value is set, it will be reset to the default of 10,000ms.
userId	No	—	Unique user identifier
deviceType	No	null	e.g. "mobile", "tv"
deviceOs	No	null	e.g. "android"
deviceOsVersion	No	null	OS version string
deviceManufacturer	No	null	Device manufacturer
deviceModel	No	null	Device model name
country	No	null	ISO 3166-1 alpha-2 country code
countryName	No	null	Human-readable country name
region	No	null	Region / state code
regionName	No	null	Human-readable region name
city	No	null	City name
dma	No	null	Nielsen DMA code
destination	No	null	Current page URL / deep-link destination
source	No	null	Referring page URL / source
playerId	No	null	Player identifier sent to Brightcove
playerName	No	null	Human-readable player name
application	No	null	Custom application identifie
debugLogging	No	false	Log all outgoing beacon URLs
includeQoEMetrics	No	false	Include bitrate/resolution/dropped-frames in engagement beacons. Disable on low-end Smart TV devices.

import com.quickplay.vstb7.player.ad.brightcove.datacollection.BrightcoveDataCollectionConfig

// 1. Build a config (only accountId and videoId are required)
val dataCollectionConfig = BrightcoveDataCollectionConfig(
    accountId = 12345,  // Numeric Brightcove account ID
    videoId = "your-brightcove-video-id",
)
brightcoveAdsPlayer?.dataCollectionConfig(dataCollectionConfig)

Listen to ad events

You can register an 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.