Ad frequency control

Ad frequency control (AFC) lets you gate ad opportunities based on content consumption and ad-break exposure. AFC is opt-in: all ad opportunities are allowed when you omit the configuration or set enable to false. This page shows how to configure AFC for IMA CSAI/SSAI, IMA DAI, and MediaTailor, and how to evaluate an SSAI preroll request in your app.

Configure AFC

AdFrequencyControlConfiguration enables AFC and defines its thresholds. The following table lists the default values. Set enable to true to enforce AFC.

Property	Default	Description
enable	false	Enables AFC enforcement.
minimumContentConsumptionMs	180_000L (3 minutes)	Minimum content consumption threshold in ms.
adBreakExposureThreshold	0.66	Ad-break exposure threshold.
allowFirstOpportunity	true	Whether AFC allows the first ad opportunity.

Create a configuration and pass it to a supported ads player:

val adFrequencyControl = AdFrequencyControlConfiguration(
  enable = true,
  minimumContentConsumptionMs = 180_000L,
  adBreakExposureThreshold = 0.66,
  allowFirstOpportunity = true
)

Use AFC with IMA CSAI or SSAI

Pass a CSAIAdsRequest or SSAIAdsRequest to the matching IMAAdsPlayerFactory.imaAdComposedPlayerWith overload with the AFC configuration.

val player = IMAAdsPlayerFactory.imaAdComposedPlayerWith(
  contentPlayer = contentPlayer,
  adRequest = adRequest,
  adFrequencyControl = adFrequencyControl
)

Use AFC with IMA DAI

Configure IMADaiAdsPlayerBuilder with AFC. This builder doesn't have a sessionURL() method, so pass the SSAI ads request and session configuration to build().

val result = IMADaiAdsPlayerBuilder()
  .mediaURL(contentUrl)
  .mediaType(MediaType.DASH)
  .adFrequencyControl(adFrequencyControl)
  .build(
    platformContext = platformContext,
    adsRequest = adsRequest,
    imaDaiSessionConfig = imaDaiSessionConfig
  )

adsRequest must be an SSAIAdsRequest. Set imaDaiSessionConfig to an IMADaiSessionConfig.PerSession or IMADaiSessionConfig.Reuse configuration.

Use AFC with MediaTailor

The MediaTailorAdsPlayerBuilder supports AFC with either a QpSessionConfiguration or a DzSessionConfiguration. Select the mode with sessionConfiguration, then build the player asynchronously:

val result = MediaTailorAdsPlayerBuilder()
  .sessionURL(sessionUrl)
  .contentURL(contentUrl)
  .sessionConfiguration(sessionConfig)
  .adFrequencyControl(adFrequencyControl)
  .buildAsync(
    platformContext = platformContext,
    isVODPlayback = isVod
  )

Gate SSAI preroll requests

Call AdFrequencyControl.evaluateOpportunity() from your content authorization flow when deciding whether to request an SSAI preroll. It returns true to request the preroll or false to skip it. When AFC is disabled, it returns true.

if (AdFrequencyControl.evaluateOpportunity()) {
  // Request the SSAI preroll from content authorization.
}

Ad Suppression Event

When AFC blocks an ad opportunity, the player emits the AD_SKIPPED_AFC_POLICY as adtracking event. Applications can use this event to identify when an ad is skipped due to AFC policy and report it to analytics for tracking and downstream analysis.