VAST for Flowplayer

.flowplayer {
background-color: #fff;
background-image: url("//flowplayer.org/media/img/logo-blue.png");
-webkit-background-size: 95%;
-moz-background-size: 95%;
background-size: 95%;
-webkit-box-shadow: 0 0 20px #b8b8b8;
-moz-box-shadow: 0 0 20px #b8b8b8;
box-shadow: 0 0 20px #b8b8b8;
font-size: 12px;
}

CSS
<div id="overlay" class="flowplayer"></div>
 
<!-- install the player with ima VAST configuration -->
<script>
flowplayer("#overlay", {
// configure the VAST plugin for this player
ima: {
// adverts configuration
ads: [{
// mandatory: schedule ad time
// here: 3 seconds into the video
time: 3,
 
// request an advert with an adTag URL
adTag: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/48717572/fp-overlay&ciu_szs&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=https%3A%2F%2Fflowplayer.org&correlator=[timestamp]"
}]
},
 

splash: true,
ratio: 5/12,
clip: {
sources: [
{ type: "application/x-mpegurl",
src: "//edge.flowplayer.org/functional.m3u8" },
{ type: "video/mp4",
src: "//edge.flowplayer.org/functional.mp4" }
]
}
});
</script>

HTML

view standalone page

Prerequisites

The Flowplayer VAST plugin is a commercial video advert solution available on a subscription basis.

Load the required IMA SDK and VAST JavaScripts in the HEAD section of your page:

<!-- player skin of your choice -->
<link rel="stylesheet" href="//releases.flowplayer.org/7.0.4/skin/skin.css">
 
<!-- jQuery is required for video tag based setups only -->
<script src="//code.jquery.com/jquery-1.12.4.min.js"></script>
<!-- Flowplayer -->
<script src="//releases.flowplayer.org/7.0.4/flowplayer.min.js"></script>
 
<!-- load the VAST assets after the Flowplayer assets -->
<!-- the IMA SDK -->
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
<!-- your VAST plugin -->
<script
src="//releases.flowplayer.org/vast/flowplayer.org/vast.min.js">
</script>

HTML

  • Important The IMA SDK must be loaded exactly as above, not from your own server.

The plugin requires Flowplayer 6.0.0 or greater.

Plugin initialization

The plugin is automatically loaded into each player unless disabled explicitly.

Pure JavaScript

The above example is a JavaScript installation into an empty container element:

<div id="overlay" class="flowplayer"></div>
 
<!-- install the player with ima VAST configuration -->
<script>
flowplayer("#overlay", {
// configure the VAST plugin for this player
ima: {
// adverts configuration
ads: [{
// mandatory: schedule ad time
// here: 3 seconds into the video
time: 3,
 
// request an advert with an adTag URL
adTag: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/48717572/fp-overlay&ciu_szs&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=https%3A%2F%2Fflowplayer.org&correlator=[timestamp]"
}]
},
 

splash: true,
ratio: 5/12,
clip: {
sources: [
{ type: "application/x-mpegurl",
src: "//edge.flowplayer.org/functional.m3u8" },
{ type: "video/mp4",
src: "//edge.flowplayer.org/functional.mp4" }
]
}
});
</script>

HTML

Video tag based

flowplayer_ima.conf

The plugin provides the flowplayer_ima.conf() command for VAST configuration of VIDEO tag based installations. As nested JSON syntax would be too complex to translate into HTML data attributes this method can be used in an inline SCRIPT tag instead. Especially useful with automatic installations where you still want to address specific players.

Automatic installation

The above example would look roughly like this in an automatic installation:

<div class="flowplayer is-splash"
id="image_text" data-ratio="0.4167">
 
<!-- configure VAST plugin for this player inline -->
<script>
// use special method instead of data attributes
flowplayer_ima.conf({
ads: [{
time: 3,
adTag: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/48717572/fp-overlay&ciu_szs&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=https%3A%2F%2Fflowplayer.org&correlator=[timestamp]"
}]
});
</script>
 
<video>
<source type="application/x-mpegurl"
src="//edge.flowplayer.org/functional.m3u8">
<source type="video/mp4"
src="//edge.flowplayer.org/functional.mp4">
</video>
 
</div>

HTML

Manual installation with jQuery

When installing into jQuery-selected container elements the plugin can be set up either way:

  • by specifying ima in the argument to the flowplayer() jQuery plugin or
  • by scripting flowplayer_ima.conf() inside the container

Plugin configuration

The plugin configuration is simple, flexible and powerful. All settings are specified in the ima (Interactive Media Adverts) configuration object. ima can be specified

in ascending order of precedence. Higher level configuration persists, unless overridden.

optiontypedescriptionsyntax
imaobjectVAST configuration on this level (global, player, clip).JSON
HTML data attribute equivalent: as argument to a flowplayer_ima.conf() inline script
imabooleanIf set to false disables the plugin for a specific player.JSON or HTML data attribute

Configuration options

These are the top-level plugin configuration options:

optiontypedescription
adRulesstringURL pointing to an XML file containing ad rules for one feature clip.
Has no effect if an ads array is configured for the same clip.
adsarrayA list of advert objects describing timed advert requests, one per advert, for one feature clip.
ads take precedence over adRules if both are configured.
adsnullSetting ads to null on the clip level explicitly prevents adverts for this clip. Useful to override defaults given on a higher level or inside the playlist array.
playlistarrayA list of clip level ima configuration objects, corresponding to each clip of a playlist.
Handy for VIDEO tag based playlist installations, as alternative to inlining flowplayer_ima.conf into each playlist item.
redirectsintegerMaximum number of redirects to try before ad load is aborted.
Default value: 4 - higher values may affect performance.
RedirectsintegerDeprecated. Use redirects.
showTitlebooleanv2.0.1 For Flowplayer version 6.x only. Whether to display official linear advert title while advert is shown.
Default value: false.
VpaidModestring / integerDetermines VPAID functionality.
Accepted values are:
"DISABLED" or 0: VPAID ads will not play and an error will be returned if VPAID is requested.
"ENABLED" or 1: VPAID is enabled using a cross domain iframe. The VPAID ad cannot access the site. VPAID ads that depend on friendly iframe access may not play. This is the default.
"INSECURE" or 2: VPAID ads are enabled. The VPAID ad will load in a friendly iframe. This allows the ad access to the site via javascript.

Additionally all advert options, except for time, can also be set at the top level of the ima configuration. They will act as default values for all adverts in an ads array.

Ads options

Each object of an ads array accepts the following options to compose an advert request:

optiontypedescription
timeintegerWhere the advert should be positioned.
In terms of a video advert:
0, pre-roll: before the feature begins.
Positive int, mid-roll: at int seconds into feature.
-1, post-roll: after the feature finishes.
Setting time is mandatory for an ad request to take effect.
Note: time cannot be set outside an ads list.
adTagstringThe complete request URL of the scheduled advert.

Native playback

When the feature is shown in native playback, i.e. on devices not supporting inline video playback or in enabled native fullscreen mode on mobile devices, adverts which feature graphical overlays in any form, like skippable video ads or non-linear graphical overlay ads, are either not shown or reduced in their functionality.

These device or configuration enforced restrictions can be mitigated with a flexible adTag configuration which prefers the interactive ad where possible, but provides a fallback alternative.

Example using the flowplayer.support feature detection mechanism in a conditional statement:

ima: {
ads: [{
// request
// a skippable pre-roll where inline playback is possible
// a standard video pre-roll otherwise
time: 0,
adTag: flowplayer.support.inlineVideo
? "https://foo.com/skippable_adtag"
: "https://foo.com/video_adtag"
}]
}

JavaScript

Global JavaScript configuration

ima can be configured in the global configuration for all players on the page.

Example:

// set the adRules for all players on this page
// to the current page
flowplayer.conf.ima = {
adRules: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/15018773/everything2&ciu_szs=300x250,468x60,728x90&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&cmsid=133&vid=10XWSh7W4so&ad_rule=1"
};

JavaScript

Global options

The following option customizes all players on the page and should only be set once in the global configuration:

optiontypedescription
enableFlashAdsbooleanv2.1.6 Flash adverts are disabled by default. Setting this to true may lead to erratic behavior. Only use this as a measure of last resort, if your publisher has not upgraded to HTML5 compatible adverts yet, while urging them to do so.
localestringThe language used by the IMA SDK for UI elements: can be any 2 letter code.
LocalestringDeprecated. Use locale.

Example:

flowplayer.conf = {
// other global player settings go here
ima: {
// brazilian interface for ads
locale: "pt_br"
}
};

JavaScript

Disabling the plugin

The plugin can be disabled for specific players by setting ima to false in the player configuration, or adding the the data-ima="false" attribute to the player container element.

Embed code with adverts

To offer embed code which will show adverts on the embedding site you must set up iframe embedding. Try it with this player. Its embed code will show an iframe of this page. The result can be found here.

Wordpress

If you are using our Wordpress plugin, you can upload the VAST plugin assests, specify the paths in the Worpdress plugin settings, and configure ad type and time in the video settings.

CSS classes

The plugin assigns the following CSS class names to the container element as state indicators when adverts are shown:

  • is-ad-visible while an advert is shown
  • is-ad-nonlinear while a non-linear (bottom third overlay) advert is shown

JavaScript API

The plugin provides listeners to all events of the IMA SDK and and easy interface to the AdError event.

Ad events

All events give access to the advert via the third argument given in the callback. Information on the ad can be retrieved using the IMA methods listed here.

Example:

flowplayer(function (api) {
// listen to the Ad LOADED event
api.on("ima_ad_loaded", function (e, api, ad) {
// is this a linear ad?
console.info(ad.isLinear());
});
});

JavaScript

As per above the notation of Flowplayer ad event types (names) is:

ima_ad_{lower cased IMA SDK ad event type}

Ad Error

The third argument of the ima_ad_error event gives direct access to the error message and error code:

flowplayer(function (api) {
api.on("ima_ad_error", function (e, api, err) {
console.info("Ad error message: " + err.message);
console.info("Ad error code: " + err.code);
});
});

JavaScript

Testing

Ad tags and ad rules can be tested directly against the IMA HTML5 SDK in its online Video Suite Inspector. Paste the adTag or adRules in the input field and click 'TEST AD'.

If the advert does not play, consult the 'Events' section below the player. Common errors and their meanings are:

  • 'Ad Error: The VAST response document is empty.' - The ads inventory of your ads provider currently contains no ads which target your site.
  • 'Ad Error: Linear assets were found in the VAST ad response, but none of them matched the video player's capabilities.' - The tag requests a Flash video advert. You should ask your ads provider to deliver HTML5 compatible video ads (usually MP4).
  • 'Ad Error: There was a problem requesting ads from the server. Inner Error: Error: Http response at 400 or 500 level' - Most probably a cross domain security (CORS) issue; you can verify this in the browser console. Ask your ad network to enable CORS.

If you need new ad tags or ad rules you can still test the functionality of the plugin with some of the sample rules/tags listed here.

Debugging

To turn on the IMA SDK's debug logging to the browser console load its debug version ima3_debug.js instead of ima3.js:

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_debug.js"></script>

HTML

Known constraints

  • Does not work with manual jQuery installations into multiple containers using a class selector
  • Internet Explorer 9 and below is not supported by the Google IMA API
  • The plugin only supports the IMA3 HTML5 API
  • the Google IMA3 SDK currently does not support skippable ads on iOS

Video advert examples

Ad rules

<div id="adrules" class="flowplayer"></div>
 
<!-- install the player with ima VAST configuration -->
<script>
flowplayer("#adrules", {
// configure the VAST plugin for this player
ima: {
// adverts configuration
adRules: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator="
},
 
// adverts in embedded player with iframe embedding
embed: {
iframe: "//flowplayer.org/standalone/vast/adrules-iframe.html"
},
 
splash: true,
ratio: 9/16,
clip: {
sources: [
{ type: "application/x-mpegurl",
src: "//edge.flowplayer.org/FlowplayerHTML5forWordPress.m3u8" },
{ type: "video/mp4",
src: "//edge.flowplayer.org/FlowplayerHTML5forWordPress.mp4" }
]
}
});
</script>

HTML

view standalone page | embedded

Pre-roll

<div id="preroll" class="flowplayer"></div>
 
<!-- install the player with ima VAST configuration -->
<script>
flowplayer("#preroll", {
// configure the VAST plugin for this player
ima: {
// adverts configuration
ads: [{
// mandatory: schedule ad time
// pre-roll
time: 0,
 
// request an advert with an adTag URL
adTag: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/48717572/fp-preroll&ciu_szs&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=https%3A%2F%2Fflowplayer.org&correlator=[timestamp]"
}]
},
 
// adverts in embedded player with iframe embedding
embed: {
iframe: "//flowplayer.org/standalone/vast/preroll-iframe.html"
},
 
splash: true,
ratio: 9/16,
clip: {
sources: [
{ type: "application/x-mpegurl",
src: "//edge.flowplayer.org/drive.m3u8" },
{ type: "video/mp4",
src: "//edge.flowplayer.org/drive.mp4" }
]
}
});
</script>

HTML

view standalone page | embedded

Skippable pre-roll

<div id="skippable" class="flowplayer"></div>
 
<!-- install the player with ima VAST configuration -->
<script>
flowplayer("#skippable", {
// configure the VAST plugin for this player
ima: {
// adverts configuration
ads: [{
// mandatory: schedule ad time
// skippable pre-roll
time: 0,
 
// request an advert with an adTag URL
adTag: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/48717572/fp-preroll-skippable&ciu_szs&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&description_url=https%3A%2F%2Fflowplayer.org&correlator=[timestamp]"
}]
},
 

splash: true,
ratio: 9/16,
clip: {
sources: [
{ type: "application/x-mpegurl",
src: "//edge.flowplayer.org/FlowplayerHTML5forWordPress.m3u8" },
{ type: "video/mp4",
src: "//edge.flowplayer.org/FlowplayerHTML5forWordPress.mp4" }
]
}
});
</script>

HTML

view standalone page

Migration from version 1.x

  • The plugin does not require the loading of a CSS stylesheet
  • The default VpaidMode is now ENABLED