Pause Ads with Player Web SDK

Schedule a pause ad

Pause ads require Player Web SDK v8.278.0 or later and the Bitmovin Advertising module. Configure an ad break with position set to 'pause':

// Use Bitmovin Advertising instead of the default IMA integration.
bitmovin.player.Player.addModule(bitmovin.player['advertising-bitmovin'].default);

const player = new bitmovin.player.Player(document.getElementById('player'), {
  key: 'YOUR_PLAYER_KEY',
  advertising: {
    adBreaks: [
      {
        tag: {
          url: 'https://your.ad.provider/pause-ad.xml',
          type: 'vast',
        },
        position: 'pause',
      },
    ],
  },
});

Alternatively, schedule a break on an existing player with player.ads.schedule():

const pauseAdBreak = {
  tag: {
    url: 'https://your.ad.provider/pause-ad.xml',
    type: 'vast',
  },
  position: 'pause',
};

player.ads.schedule(pauseAdBreak);

For runtime-only scheduling, initialize the player with advertising: {} and schedule after its source has loaded. Scheduling while content is already paused can also trigger a pause ad.

Ad processing starts if content remains paused for one second. Seeking or timeshifting during this delay restarts the timer. The ad is displayed once its image loads successfully, provided content is still paused and display is allowed.

Replay and persist pause ads

Web provides two independent options:

• discardAfterPlayback defaults to true. Set it to false to keep the break available for later pauses.
• persistent defaults to false. Set it to true to keep the break available when a new source is loaded.

The VAST tag is requested again each time the break is loaded.

For an ad that remains available across both pauses and source changes:

player.ads.schedule({
  ...pauseAdBreak,
  discardAfterPlayback: false,
  persistent: true,
});

Scheduled breaks are tried in order. With discardAfterPlayback: false, the first eligible break can be shown again on every pause; the player does not rotate between scheduled breaks.

Control ad loading and display

The existing advertising strategy callbacks shouldLoadAdBreak and shouldPlayAdBreak can also be used for pause ads, for example to prevent a break from loading or displaying.

const playerConfig = {
  key: 'YOUR_PLAYER_KEY',
  advertising: {
    adBreaks: [pauseAdBreak],
    strategy: {
      shouldLoadAdBreak: adBreak => {
        return true; // Return false to prevent this break from loading.
      },
      shouldPlayAdBreak: adBreak => {
        return true; // Return false to prevent this break from being displayed.
      },
    },
  },
};

Returning false lets the player consider the next scheduled break. The declined break remains available for later pauses only if discardAfterPlayback is false.

Error handling and fallbacks

Listen for AdError to observe loading or presentation failures. An error can be followed by a successful fallback, so it does not necessarily mean that no ad will be shown.

Pause ads support the following fallbacks:

• Try another tag: configure fallbackTags to try additional VAST tags when downloading or parsing the preceding tag fails. Image display failures do not restart the fallbackTags chain.
• Try another ad: if a VAST response contains multiple eligible ads, the player tries them in order until an image is displayed successfully. Additional ads are fallbacks, not a sequence to display. The player does not retry another variation of the same ad.
• Try another scheduled break: if a break has no usable ad or all display attempts fail, the player continues with the next scheduled pause-ad break.

Attempts stop once an ad is displayed or processing is cancelled, for example when content is no longer paused.

Presentation and customization

The Bitmovin Player UI provides a default pause-ad UI with controls to resume content or close the ad. You can adapt its appearance and controls using the UI framework; see Customising the UI for guidance.

The player also provides a default ad container. Use advertising.adContainer to supply your own HTML element and control the image's size and placement. Keep the player controls accessible above the ad.

If you build your own UI:

• Close: call player.ads.skip() to dismiss the displayed ad without resuming content.
• Resume: call player.play() to resume content and remove the displayed ad.
• Seek (optional): if your UI temporarily pauses playback while seeking, we recommend calling player.pause('ui-seek') to prevent those temporary pauses from triggering pause ads.

You can customize the ad's appearance with CSS. For example, the following adds a one-second fade-in to images in the default container:

.bitmovinplayer-overlay-container > a {
  animation: pause-ad-fade-in 1s ease-out;
}

@keyframes pause-ad-fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@media (prefers-reduced-motion: reduce) {
  .bitmovinplayer-overlay-container > a { animation: none; }
}

For a custom container, target its ad element instead.

Events and Tracking

Listen to the non-linear ad events rather than the linear ad lifecycle events:

Each event carries a NonLinearAdEvent with ad and position; for pause ads, position is 'pause'. Register listeners with player.on():

player.on(bitmovin.player.PlayerEvent.NonLinearAdStarted, event => {
  if (event.position === 'pause') {
    console.log('Pause ad displayed', event.ad);
  }
});

See Events and Tracking in the shared Pause Ads guide for VAST tracking behavior.

Limitations

• Scheduled pause-ad breaks are not returned by player.ads.list().
• Scheduled pause-ad breaks cannot be discarded through player.ads.discardAdBreak().

What's next

• Explore more ways to configure and schedule ads with the Web Player
• Browse the Player Advertising API
• Customize the Bitmovin Player UI
• Set up Server-Guided Ad Insertion with the Web Player