Skip to main content

Getting started with THEOads on Web

This guide will get you started with THEOads in your THEOplayer Web SDK: configure the license, update dependencies and set the source description.

Prerequisites​

  1. You need to have a THEOplayer license which is compatible with THEOads. This can be done through https://portal.theoplayer.com.

  2. You need a working THEOads signaling service.

  3. Your THEOplayer SDK needs to have the theoads feature enabled.

    As of THEOplayer version 8.2.0, this feature is enabled in the main theoplayer package. You can install this package with the following command:

    npm install theoplayer

Integration​

This guide assumes you know how to set up THEOplayer. For more information regarding this check out the THEOplayer getting started.

Google DAI library​

Since THEOads integrates with Google DAI Pod Serving, it is required to load the Google DAI script on your page:

<script src="https://imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

Player configuration​

To make use of the THEOads integration, first enable the feature in your player configuration:

const player = new THEOplayer.Player(element, {
  libraryLocation: 'YOUR-LIBRARY-LOCATION',
  license: 'YOUR-LICENSE-WITH-THEOADS',
  ads: {
    theoads: true
  }
});

Then, specify a source with a THEOads-enabled ad description:

player.source = {
  sources: {
    src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI',
    type: 'application/x-mpegurl',
    hlsDateRange: true,
  },
  ads: [
    {
      integration: 'theoads',
      networkCode: 'NETWORK-CODE',
      customAssetKey: 'CUSTOM-ASSET-KEY',
      backdropDoubleBox: 'PATH-TO-DOUBLE-BOX-BACKDROP-IMAGE', // Optional
      backdropLShape: 'PATH-TO-L-SHAPE-BACKDROP-IMAGE', // Optional
    },
  ],
};
  • Notice that the src is different as usual. For THEOads, a signaling server needs to be set up which acts as a proxy to parse the given manifest and insert the ad interstitials. More information can be found here.
  • The hlsDateRange flag needs to be set to true as the ad markers are done using EXT-X-DATERANGE tags.
  • The ads object needs to have its integration set to theoads. Furthermore, the networkCode and customAssetKey needs to be set according to your configured Google account.

Integrating with Open Video UI​

THEOads works seamlessly together with Open Video UI for Web. You can pass your THEOads-enabled source directly to the UI's source property:

<theoplayer-default-ui></theoplayer-default-ui>
<script>
  const ui = document.querySelector('theoplayer-default-ui');
  ui.configuration = {
    libraryLocation: 'YOUR-LIBRARY-LOCATION',
    license: 'YOUR-LICENSE-WITH-THEOADS',
    ads: {
      theoads: true
    }
  };
  ui.source = {
    sources: {
      src: 'PATH-TO-SIGNALING-SERVER/hls/MANIFEST-URI',
      type: 'application/x-mpegurl',
      hlsDateRange: true,
    },
    ads: [
      {
        integration: 'theoads',
        networkCode: 'NETWORK-CODE',
        customAssetKey: 'CUSTOM-ASSET-KEY',
      },
    ],
  };
</script>

It should look something like this:

Screenshot of Open Video UI playing a THEOads stream

More information​