How to use THEOplayer's FreeWheel pre-integration

Introduction

This guide explains how to set up THEOplayer in combination with FreeWheel, an advertisement vendor. If you are already comfortable with the THEOplayer API, you can go straight over to the FreeWheelAdDescription API. 

The following topics will be covered:

  1. Prerequisites
  2. Starting template
  3. Using FreeWheel within THEOplayer
  4. Conclusion

1. Prerequirements

There are two prerequirements in order to continue with this guide:

  1. This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial here. Be sure to have THEOplayer version 2.x.x or higher with FreeWheel enabled.
  2. This guide expects that you are a FreeWheel client and that you have ad campaigns ready for use. Information on FreeWheel can be found at https://freewheel2018.tv/

If you can place a checkmark next to these fields, you are good to go.

2. Starting Template

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent getting started guide.

To get THEOplayer to work, you only need to do three things:

  1. Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
  2. Add a container which can hold your video player with HTML.
  3. Create your player through JavaScript using our API.

A basic HTML page with a working THEOplayer could like the following:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
<title>THEOplayer 2.X: Getting Started</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href='/path/to/ui.css'> <!-- ads THEOplayer CSS -->
</head>
<body>

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

<script type='text/javascript' src='/path/to/THEOplayer.js'></script> <!-- ads THEOplayer library -->
<script>

var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
sources : [{
src : 'your.m3u8',
type : 'application/x-mpegurl'
}]
};

</script>
</body>
</html>

 Pretty self-explanatory, isn't it?

<link rel="stylesheet" type="text/css" href='/path/to/ui.css'> <
<script type='text/javascript' src='/path/to/THEOplayer.js'></script> 

The two snippets above are the references to the JS and CSS library.

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

The snippet above is your HTML container.

<script>

var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
sources : [{
src : 'your.m3u8',
type : 'application/x-mpegurl'
}]
};

</script>

The snippet above initializes your player, including a HLS source.

To fully master THEOplayer, be sure to read up our documentation.

3. Integrating FreeWheel

Starting from the basic template above, you need to add the FreeWheel MRM client SDK to the page:

<script type='text/javascript' src='https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js'></script>

 Next, you add a FreeWheelAdDescription to your source that specifies the FreeWheel tokens.

player.source = {
  sources : [{
    src : 'your.m3u8',
    type : 'application/x-mpegurl'
  }], 
  ads: [{
    integration: 'freewheel',
    networkId: 96749,
    assetId: 'DemoVideoGroup.01',
    profile: 'global-js',
    assetDuration: 22,
    adServerUrl: 'https://demo.v.fwmrm.net/ad/g/1',
    siteSectionId: 'DemoSiteGroup.01',
    cuePoints: [{ adUnit: 'preroll' }]
  }]
};

We configure cuePoints in this example. This is needed for some set-ups or completely option for others. THEOplayer will create a FreeWheel temporalSlot behind the screens, which is a request to schedule an advertisement at said point. It is up to FreeWheel (and the campaign settings) to decide whether or not it will insert an advertisement at this requested time. Not all campaigns need it and for some campaigns the requested cuePoints might even be ignored by FreeWheel.

Your updated starting template would now look like this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
<title>THEOplayer 2.X: Getting Started</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href='/path/to/ui.css'> <!-- ads THEOplayer CSS -->
</head>
<body>

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

<!-- make sure to link to a valid version number -->
 <script type='text/javascript' src='https://mssl.fwmrm.net/libs/adm/6.xx.x/AdManager.js'></script>
<script type='text/javascript' src='/path/to/THEOplayer.js'></script> <!-- adds THEOplayer library -->
<script>
player.source = { sources : [{ src : 'your.m3u8', type : 'application/x-mpegurl' }], ads: [{ integration: 'freewheel', networkId: 96749, assetId: 'DemoVideoGroup.01', profile: 'global-js', assetDuration: 22, adServerUrl: 'https://demo.v.fwmrm.net/ad/g/1', siteSectionId: 'DemoSiteGroup.01', cuePoints: [{ adUnit: 'preroll' }] }] };
</script>
</body>
</html>

Extra resources:

  1. THEOplayer Getting Started Guide
  2. FreeWheelAdDescription
  3. FreeWheel website