VAST plugin for Flowplayer

Earn money by VAST advertising

CSS code

.flowplayer {
  background-color: #fff;
  background-image: url(/{{ config.flowplayer7.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

Deprecation

Prerequisites

The Flowplayer VAST plugin was a commercial video advert solution which was available on a subscription basis Please see Deprecation for new offerings.

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

<!-- the player skin -->
<link rel="stylesheet" href="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/skin/skin.css">

<!-- jQuery is required for video tag based setups only -->
<script src="{{ config.flowplayer7.jquery }}"></script>
<!-- Flowplayer -->
<script src="{{ config.flowplayer7.releases }}/{{ config.flowplayer7.version }}/flowplayer.min.js"></script>
<!-- IMA3 -->
<script src="{{ config.flowplayer7.ima3 }}"></script>
<!-- VAST / ads plugin , replace with YOUR plugin-->
<script src="{{ config.flowplayer7.releases }}/vast/flowplayer.com/vast.min.js"></script>
<!-- OR the new ad plugin
  <script src="https://cdn.flowplayer.com/releases/ads/flowplayer.com/flowplayer.ads.js"></script>
-->

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

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

• globally for all players
• for a specific player
• at clip level, also for playlists

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

Configuration options

These are the top-level plugin configuration options:

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:

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:

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

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]({{ config.flowplayer7.standalonedemos }}/vast/adrules.html)

[View standalone page with embedded ad]({{ config.flowplayer7.demos }}/ads/embedded-ads.html#ad-rules)

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]({{ config.flowplayer7.standalonedemos }}/vast/preroll.html) [View standalone page with embedded ad]({{ config.flowplayer7.demos }}/ads/embedded-ads.html#pre-roll)

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]({{ config.flowplayer7.standalonedemos }}/vast/skippable.html)

Migration from version 1.x

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

[MINITOC]