Advertising

Schedule and play VAST ads on a source

📘
Advertising support was added in player version 10.2.0.

Player Web X can schedule and play client-side ads described by VAST 4.x ad tags. Ads are scheduled per source and play back through the same video element as the content, with pre-roll, mid-roll and post-roll positioning.

Enabling advertising

Advertising is provided by the BitmovinAdvertisingBundlePackage, which composes the three advertising packages (AdvertisingBase, AdvertisingApi, AdvertisingBitmovin) in the required order.

It is included out of the box in the Playback and BitmovinV8 bundles. When you use one of those bundles, the advertising API is available on every content source without any extra setup.

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Bitmovin Player Web X Advertising Demo</title>
  <script type="text/javascript" src="https://cdn.bitmovin.com/player/web_x/10/bundles/playerx-playback.js"></script>
</head>
<body>
  <div id="player-container"></div>

  <script type="text/javascript">
    const player = bitmovin.playerx.Player({
      key: 'YOUR-PLAYER-KEY',
      defaultContainer: document.getElementById("player-container"),
    });

    const sourceConfig = {
      resources: [{
        url: 'https://cdn.bitmovin.com/content/assets/streams-sample-video/tos/m3u8/index.m3u8',
        type: 'hls',
      }]
    };

    const sourceApi = player.sources.add(sourceConfig);

    sourceApi.ads.schedule({
      tag: {
        type: 'vast',
        url: 'https://YOUR-AD-SERVER/vast.xml',
      },
      position: 'pre',
    });

    sourceApi.play();
  </script>
</body>
</html>

If you build a custom bundle that does not already include advertising, add the bundle package yourself:

import { Player } from '@bitmovin/player-web-x/bundles/playerx-hls';
import { BitmovinAdvertisingBundlePackage } from '@bitmovin/player-web-x';

const player = Player({
  key: 'YOUR-PLAYER-KEY',
  defaultContainer: document.getElementById("player-container"),
});

player.packages.add(BitmovinAdvertisingBundlePackage);

Content sources and ad sources

The advertising API surface on source.ads depends on what kind of source it is, discriminated by the isAd flag:

Content sources (isAd: false) — regular playback sources. These expose the full scheduling API (schedule, discard, list, getActive*). This is the common case and is covered in Scheduling ads.
Ad sources (isAd: true) — a source that is itself a single ad. These expose a thin, read-only facade (id, externalAdId, skipDelay, and skip() when the ad is skippable).

Only content sources schedule ads. On an ad source, or on a content source before any ad is scheduled, the scheduling methods are not applicable.

Where to go next

Scheduling ads — the source.ads API, ad configuration, positions, and the Ad object.
Using events — reacting to the ad lifecycle through source.events.