Advertising User Guide

 

Introduction

THEOplayer allows you to configure different aspects of its advertising environment. By following this guide you’ll learn how to add different types of ads and specify constraints on the ads that are shown with your content. You’ll also learn how to configure the player to block itself when an Adblocker is present or how to define custom handlers for such blockers.

Table of contents

Feature Overview

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.

An overview of THEOplayer's different ad types

THEOplayer has support for Linear, Non-linear and Companion VAST ads and custom banner 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.

Banner overlays can be used to place strategic advertisements on-top-of the video. This allows you to monetize your content. Banner ads work in the same way as VAST non-linear ads, with the difference that they can be configured more flexible directly in the configuration of THEOplayer.

Basic Ad Configuration

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
url (required) This mandatory parameter allows you to specify the location of the VAST advertisement xml file.

Example

The following example is shown in the video below. It also shows the use of the offset and skip parameters, which we'll study next.

configuration : {
    ads: {
        vast : [
	    {
	         url: 'http://example.com/vast-preroll.xml',
                 offset: 'pre',
                 skip: 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
offset (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%
  • pre/post: The value 'pre' signifies that the video is a preroll and should be played before the actually video can be viewed. The value 'post' signifies that the video is a postroll and should be played after the original video.
  • positions: in the format #n where n is a positive number that determines the position of the ad. This type of offsets are useful when livestreaming, as all the advertisements specified this way will appear in the stated order when an adbreak is started through the AdsController.

Example

configuration : {
    ads: {
        vast : [
	    {
	         url: 'http://example.com/vast-preroll.xml',
                 offset: 'pre'
                 // other formats
                 // offset: 'post'
                 // 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
skip (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

configuration : {
    ads: {
        vast : [
            {
                url: 'http://example.com/vast-preroll.xml',
                offset: 'pre',
                skip: 5
                // other values
                // skip: -1
                // skip: 10
            }
        ]
    }
}

Choosing where to place companion ads

THEOplayer allows you to specify a companionRequest-handler. This allows you to choose where companion ads should be displayed on your website. This way, you can optimally integrate ads with the layout of your page. When a companion ad is to be added, DOM-elements will be served to this handler. These elements can be added to the page where they fit best.

Attribute Description
addCompanionsRequest(companions) (optional) This optional parameter serves as a handler function, which receives the companion ad DOM-elements that should be added to the page to display companion ads. This allows you to choose the placement of companion ads to better fit the page layout.

Example

configuration : {
    ads: {
        vast : [
            {
                url: 'http://example.com/vast-preroll.xml',
                offset: 'pre',
                skip: 5,
                addCompanionsRequest : function(companions){
		    var container = document.getElementById('my-companions-container');
                    container.className = 'my-companion-styling';
                    for (i = 0; i < companions.length; i += 1) {
                        container.appendChild(companions[i]);
		    }
		}
            }
        ]
    }
}

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 skip delay and the addCompanionsRequest 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
url (required) This parameter specifies the location of the VMAP advertisement xml file.
skip (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
addCompanionsRequest(companions) (optional) This optional parameter serves as a handler function, which receives a list of companion ad DOM-elements that should be added to the page to display companion ads. This allows to choose the placement of companion ads to better fit the page layout.

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.

configuration : {
    ads: {
        vmap : {
            url: 'http://example.com/vmap.xml',
            skip: 5,
            addCompanionsRequest : function(companions){
		var container = document.getElementById('my-companions-container');
                container.className = 'my-companion-styling';
                for (i = 0; i < companions.length; i += 1) {
                    container.appendChild(companions[i]);
		}
	    }
        }
    }
}

Adding and configuring interactive VPAID ads

Our player implements the VPAID 2.0 Javascript interface. 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.

THEOplayer will automatically detect and instantiate VPAID ads if a MediaFile's apiFramework attribute is set to 'VPAID'. There are no other technicalities to adding well-written VPAID ads. The VPAID specification explains how to create those ads and how to easily integrate them with VAST manifests. The video below contains 3 VPAID ads: one interactive pre-roll, a click-to-linear banner and a simple ad that has a custom mute/unmute interface which plays 10s after the video has started.

Adding and configuring custom Banner ads

Banners can be configured to be made semi-transparent or show up and hide automatically on predefined points in time depending on where in the content the user is currently viewing. This offers you the possibility to add for example banners specifically related to the content shown at that moment in the video. The table below shows the available options for banner customization.

Attribute Description
imageURL (required) This parameter must provide a link to the banner that should be shown as an overlay above the video.
clickURL (required) This parameter must provide a link to which the user should be redirected when clicking the ad.
opacity (optional) Parameter that allows you to make the ad semi-transparent. This allows you to still partially see the content below and makes the ad less obtrusive. The value should be set as a floating-point number between 0 (fully transparent) and 1 (fully opaque). By default the ad is not transparent.
startTime (optional) Defines the start time of the ad in seconds.
endTime (optional) Defines the end time of the ad in seconds.
maxHeight (optional) Defines the maximum height of the ad. Should be specified as a string with the appropriate units, for example px, em or %.
closeable (optional) Boolean parameter that allows you to make the ad closeable.

Example Configuration

Below you can see an example configuration for THEOplayer - displaying a banner ad from 5s to 25s of playback. When the video has played for 45s, a new banner will display until the end of the video or until it is closed.

theoplayer = {
    configuration : {
        ads: {
            banners : [{
                imageURL: "http://www.example.com/files/banner1.jpg",
                clickURL: "http://www.theoplayer.com",
                opacity: 0.6,
                startTime: 5,
                endTime: 25,
                maxHeight: '13%',
                closable: true
            },
            {
                imageURL: "http://www.example.com/files/banner2.jpg",
                clickURL: "http://www.theoplayer.com",
                opacity: 1,
                startTime: 45,
                maxHeight: '20%',
                closable: false
            }]
        }
    }
}

Blocking the player when an Adblocker is detected

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.

Example Configuration

theoplayer = {
    configuration : {
        ads: {
            blockOnAdBlock: true
        }
    }
};

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

Adblock blocker message

Advanced Ad Configuration

Adding VAST, VMAP & VPAID on the fly

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 AdsController’s addVast(url, offset, skip, addCompanionsRequest) function which will add the given VAST file as if it were specified in the initial configuration. A similar addVmap(url, skip,addCompanionsRequest) function is also available. Note that VPAID ads are integrated with VAST files, so we don't need a separate function.

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.

Example Code

Following script will load in several VAST and VPAID ads specified by multiple VAST files when THEOplayer is loaded. It also sets up a VMAP file.

theoplayer.onReady = function () {
    var adsController = theoplayer.controller(0,'AdsController');

    adsController.addVast('preroll.xml', '0%', 5, addCompanionsRequest);
    adsController.addVast('midroll-1.xml', 10, 0);
    adsController.addVast('vpaid-roll.xml', '50%', -1,);
    adsController.addVast('postroll.xml', 'post', -1);
		adsController.addVmap('vmap.xml');
};

Specifying custom Adblock Detection behavior

THEOplayer allows the configuration of custom solutions to ad blockers. When adblock is detected, the adblockdetected event will be dispatched on the AdsController. Custom code can be deployed by listening to this event.

Example Code

Example of a custom solution: displaying an alert.

theoplayer.onReady = function () {
    var adsController = theoplayer.controller(0, 'AdsController');

    adsController.addEventListener('adblockdetected', function() {
        alert("We have noticed you're using an ad blocker. Please turn it off to support this website.");
    })
};

NOTE: Please note that the adblockdetected event can also be dispatched when an invalid url is specified in the configuration of ads.