VAST for Flowplayer

Earn money by VAST advertising

CSS code
.flowplayer {
  background-color: #fff;
  background-image: url("//flowplayer.com/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;
}
HTML code
<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>

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:

<!-- the player skin -->
<link rel="stylesheet" href="https://releases.flowplayer.org/7.2.4/skin/skin.css">

<!-- jQuery is required for video tag based setups only -->
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<!-- Flowplayer -->
<script src="https://releases.flowplayer.org/7.2.4/flowplayer.min.js"></script>

{{ overlay.refs }}

The IMA SDK must be loaded exactly as above, not from your own server.
The VAST plugin src must be replaced with the one for your subscribed domain. The plugins are domain-locked and will work on the susbcribed domain only.

The plugin requires Flowplayer 7.x 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>

Video tag based

flowplayer_ima.conf {flowplayer-imaconf}

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>

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.

option type description syntax
ima object VAST configuration on this level (global, player, clip). JSON
HTML data attribute equivalent: as argument to a flowplayer_ima.conf()inline script
ima boolean If set to falsedisables the plugin for a specific player. JSON or HTML data attribute

Configuration options

These are the top-level plugin configuration options:

option type description
adRules string URL 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.
ads array A list of advert objects describing timed advert requests, one per advert, for one feature clip.
ads take precedence over adRules if both are configured.
ads null Setting 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.
adsRenderingSettings object Gives access to the IMA SDKconfiguration object of the same name.
playlist array A list of clip level ima configuration objects, corresponding to each clip of aplaylist.
Handy forVIDEO tag based playlist installations, as alternative to inliningflowplayer_ima.conf into each playlist item.
redirects integer Maximum number of redirects to try before ad load is aborted.
Default value: 4 - higher values may affect performance.
Redirects integer Deprecated. Use redirects.
showTitle boolean v2.0.1 For Flowplayer version 6.x only. Whether to display official linear advert title while advert is shown.
Default value: false.
VpaidMode string / integer Determines 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.
vastLoadTimeout integer v2.1.7 The maximum time in milliseconds the plugin should grant a single wrapper request to succeed.
Default value: 5000.

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:

option type description
time integer Where 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.
adTag string The 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"
  }]
}

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"
};

Global options

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

option type description
enableFlashAds boolean v2.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.
locale string The language used by the IMA SDK for UI elements: can be any 2 letter code.
Locale string Deprecated. Use locale.

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());
  });
});

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);
  });
});

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.

Video advert examples {video-advert-examples}

Ad rules

HTML code
<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>

View standalone page

View standalone page with embedded ad

Pre-roll

Code:

<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=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator="
    }]
  },

  // 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>

View standalone page View standalone page with embedded ad

Skippable pre-roll

Code:

<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>

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