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 enabled to false.

This page shows how to configure AFC for those ad types and how to evaluate a preroll request in your app.

Configure AFC

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

Property	Default	Description
enabled	false	Enables AFC enforcement.
minimumContentConsumptionInMS	180000 (3 minutes)	Minimum amount of content, in milliseconds, the user must watch after an exposed ad break before the next ad break is allowed to play.
adBreakExposureThreshold	0.66	Minimum fraction of an ad break the user must watch for it to count as sufficiently exposed. A value of 0.66 represents 66% exposure.
allowFirstOpportunity	true	Always allows the first ad opportunity (for example, the preroll) to play, even when AFC is enabled.

How AFC works

AFC suppresses ad breaks when the user has recently seen ads, so viewers don't see ads too often.

1. Ad opportunity check: The player evaluates whether AFC is enabled.
2. First opportunity: If allowFirstOpportunity is true, the first ad opportunity in a playback session can play.
3. Exposure check: After an ad break plays, AFC checks whether the user watched at least adBreakExposureThreshold of it. With the default 0.66, the user must watch 66% or more for the ad break to count as exposed.
4. Suppression window: After an exposed ad break, AFC suppresses upcoming ad breaks until the user has watched minimumContentConsumptionInMS of content. With the default value, ad breaks are suppressed for the next 3 minutes of content.
5. Next ad break: Once the user completes minimumContentConsumptionInMS of content, the next ad break is allowed to play.

note

If the user doesn't watch an ad break up to adBreakExposureThreshold, it doesn't count as exposed, so AFC doesn't start a suppression window for it.

Create a configuration and pass it to the ads player builder. The examples in the following sections use this configuration.

const adFrequencyControl: AdFrequencyControlConfiguration = {
  enabled: true,
  minimumContentConsumptionInMS: 180000, // User must watch 3 minutes of content
  adBreakExposureThreshold: 0.66, // Ad break counts as exposed after 66% is watched
  allowFirstOpportunity: true, // Always play the first ad, such as the preroll
};

Use AFC with IMA CSAI

Pass AdFrequencyControlConfiguration to the IMA CSAI player builder when you want the client to suppress ad opportunities until the playback thresholds are met.

const adPlayer = createImaPlayerBuilder()
  .ima(window.google.ima)
  .adRequest({ adTagUrl: adTagUrl, slotWidth: 1080, slotHeight: 720 })
  .contentPlayer(contentPlayer)
  .contentVideoElement(videoElement)
  .contentContainerElement(videoWrapper)
  .adFrequencyControl(adFrequencyControl)
  .build();

Use AFC with IMA DAI

Configure AFC on the DAI ad player builder when you use the Google IMA DAI stream manager. This keeps the ad opportunity gating logic in the player layer while the DAI session handles stream creation.

const adsPlayer = createImaPlayerBuilder()
  .ima(window.google.ima)
  .imaDaiManager(daiMetadata.streamManager)
  .contentPlayer(contentPlayer)
  .contentVideoElement(videoElement)
  .contentContainerElement(videoWrapper)
  .adFrequencyControl(adFrequencyControl)
  .build();

Use AFC with MediaTailor

For MediaTailor, gate preroll session creation in your app before you initialize the MediaTailor session and create the ad player. When AFC blocks the opportunity, skip session initialization and continue with content playback.

const mediatailorSession = createMediatailorSession();

const mediatailorMetadata = await mediatailorSession.initialize(
  mediatailorInitializationData,
  palConfiguration,
);

const contentPlayer = playerBuilder
  .mediaElement(videoElement)
  .mediaUrl(mediatailorMetadata.manifestUrl)
  .mediaType(MediaType.HLS)
  .build();

const adsPlayer = mediatailorSession.createMediatailorPlayer(
  contentPlayer,
  mediatailorMetadata,
  adPlaybackPolicy,
  logger,
  videoElement,
  adFrequencyControl,
);

Gate preroll requests

Call getAdfrequencyController().evaluateOpportunity() from your preroll request flow to decide whether to request an ad session. It returns true to request the preroll or false to skip it. When AFC is disabled, it returns true.

if (getAdfrequencyController().evaluateOpportunity()) {
  // Request the preroll from the authorization or session flow.
}

Ad Suppression Event

When AFC blocks an ad opportunity, the player emits the adskip_afc_policy 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.

adsPlayer.subscribe('adskip_afc_policy',(event)=>{
  // Report this event to analytics for tracking.
});

Enable logs in AFC

Application / Ad players consuming AFC can able to enable log by configuring logger levels.

getAdfrequencyController().evaluateOpportunity().setLoggerLevel(LoggerLevel.DEBUG)