Advertising User Guide 2.X

 

Introduction

THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you’ll learn three things:

  1. How to configure ads.
    1. How to configure basic ads.
    2. How to schedule ads on the fly.
  2. How to use integrations such as Google IMA for DFP and SpotX.
  3. How to configure the player to block itself when an Adblocker is present or how to define custom handlers for such blockers.

We first discuss advertisements and how they are implemented in THEOplayer.

Table of contents

  1. Feature Overview

    1. An overview of THEOplayer's Advertisement tools
    2. An overview of THEOplayer's different ad types
  2. Ad Implementations

    1. THEOplayer
    2. Google IMA
    3. Others
  3. Ad Configuration

    1. Basic Ad Configuration
      1. Adding and configuring VAST ads
      2. Control the ads shown alongside your content with VMAP
      3. Adding and configuring interactive VPAID ads
    2. Advanced Ad Configuration
      1. Dynamic Ad Scheduling
      2. Example: Livestreams + Ads + Google IMA
  4. Adblock detection

1. Feature Overview

1.1. An overview of THEOplayer's Advertisement tools

THEOplayer offers an array of features that allow you to take total control over your online video content’s advertisement environment.

To facilitate integration between content providers and ad servers, we implement the IAB Video Suite, a set of technical specifications that is widely used by many participants in the online video advertisement industry. More specifically, we implement the following IAB specifications: Digital Video Ad Serving Template (VAST), Digital Video Multiple Ad Playlist (VMAP) and Digital Video Player-Ad Interface Definition (VPAID). You'll have to get acquainted with these specifications if you want to optimize your advertisement revenue.

On top of the IAB suite, THEOplayer comes with additional tools to improve advertisement efficiency, like e.g. Adblock Detection.

Digital Video Ad Serving Template (VAST)

The Digital Video Ad Serving Template (VAST) specification is a description for video ads that standardizes communication requirements between video players and ad server. It gives instructions to the video player on how ads should be handled and displayed. It can define how and how long the ad should be displayed, if and when it can be skipped and how to give tracking information to the ad servers.

THEOplayer offers support for delivery of video ads with VAST 3.0. Support is available for linear ads (prerolls, midrolls, postrolls and adbreaks), non-linear ads (overlay banners) and companion banners, all of which are discussed in the next section.

Digital Video Multiple Ad Playlist (VMAP)

With Digital Video Multiple Ad Playlist (VMAP), video content owners can exercise control over the ad inventory displayed with their content when they can’t control the video player, to capitalize on advertising while maintaining the integrity of their program content. VMAP enables the content owner to define the ad breaks within their content, including the timing for each break, how many breaks are available, what type of ads and how many are allowed in each break.

Digital Video Player-Ad Interface Definition (VPAID)

VPAID establishes a common communication protocol between video players and ad units that allows a single “executable ad” (one that requires software logic to be executed as part of ad playback) to be displayed in-stream with the publisher’s video content. It allows the ad and the player to expect and rely upon a common set of functionality. The significance is that advertisers using VPAID ads can provide rich ad experiences for viewers and collect ad playback and interaction details that are just as rich as the ad experience. With the adoption of VPAID, advertisers have more control over the display experience in their video campaigns. VPAID ads can easily be integrated on top of VAST manifests.

Adblock Detection

Ad blockers or filters (such as the AdBlock plugin for browsers) remove or alter ads on webpages such that they become less obtrusive for the user. They can be a big threat to websites that get their revenue from video advertisements as they prevent an ad from being played. THEOplayer has built-in features that can detect ad blockers and act accordingly.

1.2. An overview of THEOplayer's different ad types

THEOplayer has support for Linear, Non-linear and Companion VAST and VPAID ads, as well as for VMAP ads.
THEOplayer currently supports two ad playback implementation:

  1. THEOplayer (default)
  2. Google IMA 

Below you can find the support matrix for different type of ads:

  VAST VMAP VPAID
THEOplayer Yes Yes No
Google IMA Yes Yes Yes

VAST, VMAP and VPAID files contain different type of ads.

Linear Ads

Linear ads are video ads that play before, during or after the content video. THEOplayer allows you to specify an optional offset to make a linear ad play at a given time during or after the video. Linear ads can be further configured by specifying how long the ad must be watched before the user can skip it. Linear ads can be interactive (VPAID) or can simply have a click through that directs users to a webpage in a different screen.

Non-linear Ads (overlays)

Non-linear ads are shown on top of the video as an overlay during playback. The user can interact with these ads by clicking them, which will for example redirect them to a page with more information about the product being advertised. Non-linear ads can also be closed by users.

Companion Ads

Companion banners are ads surrounding the video player that, in comparison with linear and non-linear ads, do not directly interfere with a user’s viewing experience. THEOplayer allows you to choose where the companion ads should be displayed on your website so it better integrates with the layout of the page.

2. Ad Integrations

Advertisement are described through the AdDescription object in the API. Besides defining a source, you can also define the integration property. The possible values of this property are:

  • 'google-ima'
  • 'spotx'

2.1. THEOplayer

The THEOplayer ad system will be used by default. You don't have to indicate this preference, and you can omit the integration property.

2.2. Google IMA

To use the Google IMA integration you have to set the integration key to 'google-ima' as seen below:

player.source = { 
    sources: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{ 
        sources: '//cdn.theoplayer.com/demos/preroll.xml',
        integration: 'google-ima' 
    }] 
}; 

In order for Google IMA to work, you also have to load in the Google IMA SDK:

<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

2.3. Others

THEOplayer pre-integrates with some advertisement systems to facilitate the development.

SpotX

Set the integration property to 'spotx' to configure SpotX ads. More information can be found at https://support.theoplayer.com/hc/en-us/articles/214350425-SourceDescription-API#spotxaddescription.

3. Ad Configuration

3.1. Basic Ad Configuration

3.1.1. Adding and configuring VAST ads

As we discussed in An overview of THEOplayer's Advertisement tools, VAST gives instructions to the video player on how ads should be handled and displayed. This guide does not go into the details of how to create a VAST file. We only refer to the VAST specification, a good starting point if you want to learn the skill. Here, we’ll discuss how you can add existing VAST ads to THEOplayer. The player supports VAST by specifying an URL parameter to the VAST description in the player configuration. An example can be found below. The player will automatically load this advertisement description and act accordingly.

Attribute Description
sources
(required)
This mandatory parameter allows you to specify the location of the VAST advertisement xml file.

Example

The following example shows the use of the offset and skip parameters, which we'll study next.

player.source = {
    source: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{
	sources: 'http://example.com/vast-preroll.xml',
        timeOffset: 'start',
        skipOffset: 5
    }]
}

Specifying an offset for your ad

You can specify an optional offset parameter that indicates at what time the ad should be displayed before, during or after the video. This parameter works for linear as well as non-linear and companion ads and has the following specification:

Attribute Description
timeOffset
(optional)
This optional parameter allows you to determine the place of the specified ad. Five different formats are allowed:
  • seconds: a numeric value representing the number of seconds into the video the ad should play
  • time: in the format hh:mm:ss.mmm (.mmm is optional), for example '00:35:30.000'
  • percentage: in the format n%, where n is a value from 0-100, for example 50%
  • start/end: The value 'start' signifies that the video is a preroll and should be played before the actually video can be viewed. The value 'end' signifies that the video is a postroll and should be played after the original video.

Example

player.source = {
    source: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{
	sources: 'http://example.com/vast-preroll.xml',
        timeOffset: 'start'
        // other formats
        // offset: 'end'
        // offset: '00:08:15.500'
        // offset: '50%'
    }]
}

Configuring your ad to be skippable

You can allow an ad to be skipped by adding a skip parameter in the configuration. The skip parameter describes how long - in seconds - the ad must be watched before the user can skip it. The parameter is optional, if you don’t define one, THEOplayer will use the information specified by the VAST file itself.

NOTE: Note that ad-skipping is currently not supported on iPhone.

Attribute Description
skipOffset (optional) This optional parameter allows you to override the amount of seconds a viewer must watch the advertisement before it can be skipped. A negative value of -1 disables ad skipping (even if the VAST file specifies a skip delay).

Example

player.source = {
    source: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{
	sources: 'http://example.com/vast-preroll.xml',
        skipOffset: 5
        // other values
        // skip: -1
        // skip: 10
    }]
}

Choosing where to place companion ads

THEOplayer allows you to render companion ads where ever you want. This way, you can optimally integrate ads with the layout of your page. When a companion ad is in the VAST/VMAP/VPAID, you can detect them through an event listener. These elements can be added to the page where they fit best.

Example

player.ads.addEventListener('adbegin', function(e) {
   if (e.ad) {
       for (var i = 0; i < e.ad.companions.length; i++) {
	    // do something with e.ad.companions[i] 
	    // and e.ad.companions[i].contentHTML to display it
       }
   }
});

player.ads.addEventListener('adend', function(e) {
   // remove companions ads
});

3.1.2. Control the ads shown alongside your content with VMAP

The VMAP protocol uses VAST 3.0 files to specify the content of the advertisements. Again, we will not explain how you should create VMAP files, you can read more on that in the VMAP specification. Configuration of the skipOffset delay can be done similarly as in the VAST configuration, discussed in Adding and configuring VAST ads. The following table summarizes the possibilities and effects of each option.

Attribute Description
sources (required) This parameter specifies the location of the VMAP advertisement xml file.
skipOffset (optional) This optional parameter allows to override the amount of seconds a viewer must watch a pre-roll ad before it can be skipped. A negative value of -1 disables ad skipping. This will affect all linear ads specified in the VMAP file

Example VMAP configuration

Example of a VMAP configuration where all videos it contains will be skippable after 5 seconds. Please note that VMAP files are able to restrict their VAST files so only linear ads will be loaded in, which means that no companions will be added.

player.source = {
    source: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{
	sources: 'http://example.com/vmap.xml',
        skipOffset: 5
    }]
}

3.1.3. Adding and configuring interactive VPAID ads

Our player implements the VPAID 2.0 Javascript interface through the Google IMA integration. This version of the specification is designed to further facilitate VPAID integration with VAST. This means that you can embed rich VPAID ads in your VAST manifests and add those manifests to our player, as we've shown in Adding and configuring VAST ads.

Example VPAID configuration

player.source = {
    source: [{ 
        src : 'http://cdn.theoplayer.com/video/big_buck_bunny/big_buck_bunny_metadata.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{
	sources: 'http://example.com/vpaid.xml',
        integration: 'google-ima'
    }]
}

NOTE: The timeOffset property isn't supported in the Google IMA integration. Use VMAP ads to schedule mid-roll and post-rolls.

3.2. Advanced Ad Configuration

3.2.1. Dynamic Ad Scheduling

In Basic Ad Configuration, we learned how to statically add ads to THEOplayer on startup by specifying them in the configuration object. However, several interesting use cases exist that require on the fly ad injection, for example when VAST files should be added by a script provided by an external ad server.

To dynamically add advertisements, you should use the player.ads.schedule(AdDescription) function which will add the given ad file as if it were specified in the initial configuration. The AdDescription -which you will pass as a parameter to the function- is the same object as previously discussed in 3.1.

NOTE: Please note that when adding a pre-roll when the original video is already playing (for example because of autoplay), the pre-roll cannot start playing. An advertisement with an offset of '0%' will always be able to play.

 

3.2.2. Example: Livestream +Ads + Google IMA

Example Code

A common use case is a developer wanting to schedule ads in a livestream. 

This example is pretty straightforward, and the developer only has two challenges:

  • Setting up a livestream
  • Inserting an advertisement on the fly

1. Setting up a livestream
First, a new livestream is configured through the THEOplayer API. Optionally, a pre-roll is can be added to a livestream:

player.source = { 
    sources: [{ 
        src : 'livestream.m3u8',
        type : 'application/x-mpegurl'
    }], 
    ads: [{ 
        sources: '//cdn.theoplayer.com/demos/preroll.xml',
        timeOffset: 'start' 
    }] 
}; 

2. Inserting an advertisement on the fly
The timing of the insertion is up to the developers. A proper method to insert ads in livestreams is to use ID3 metadata. Once specific ID3 metadata is detected, an ad will be scheduled with the schedule() method, as described by the Ads API:

player.ads.schedule({
    sources: 'vast.xml',
    integration: 'google-ima'
});

Of course, you could also count down to a specific moment using a timeupdate event, or provide a button (as illustrated by http://demo.theoplayer.com/schedule-ad-example) to schedule an ad.

4. Adblock detection

THEOplayer offers the option to block the player when an ad blocker is detected. This can be achieved by setting blockOnAdBlock in the configuration.ads object to true. The player will display a message saying it has detected an ad blocker and that the user will need to turn it off in order to watch the video.

A more in-depth code-example can be found at http://demo.theoplayer.com/adblock-detection.

Example Configuration

// add an eventlistener to get custom behavior if there is an ad error
player.ads.addEventListener('aderror', function (event) {
    // do something
});

// set the player source with ads and the blockContentIfAdError property
player.source = {
    sources: {
        src: '...'
    },
    ads: [{
        sources: 'http://cdn.theoplayer.com/demos/advertisement/livereal-no-skip.xml'    
    }],
    // set this to true if you want to block the content
    // default value is false
    blockContentIfAdError: true
}

The default message that is shown when ad block is detected is depicted below.

Adblock blocker message