Advertising plugin

The Advertising plugin allows to play video and text/overlay ads from multiple VAST (versions 2, 3 or 4)/VPAID (version 2) compliant tags or a single VMAP / adPod tag.

Installation

Manual installation

Load the core player and the Advertising plugin.

For versions before v3.4.5, you also need to load the Google IMA3 SDK.

<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>
<!-- for player versions before 3.4.5>
<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script> -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/ads.min.js"></script>

Configuration

You can configure the plugin manually using JavaScript.

Core plugin configuration

Ads are configured with the top level configuration option ima.

UI configuration

Example

flowplayer('#player_container', {
  src: 'my_video.mp4',
  token: '<my_token>',
  ads: {ui: flowplayer.ads.ui.AD_CHOICES | flowplayer.ads.ui.AD_REMAINING_TIME},
  ima: {...}
})

Configuration example code

Javascript ima: object

"ima": {
        "ads":
         [
          { "time": 0, "adTag": "https://mydserver.com/path/vast.xml" }, // ad 1: preroll
          { "time": 20, "adTag": "https://mydserver.com/path/vast2.xml" }, //ad 2: midroll at 20 seconds
          { "time": 300, "adTag": "https://mydserver.com/path/vast3.xml" } //ad 2: midroll at 300 seconds
        ]
        ,"parameters": { "age": 25, "location": "us" }
        , "show_all_ads_on_seek" : false // do not show first and second midroll if user seeks after 300 seconds
        , "indicator": false // disable ad indicator
        , "ui":
      }

API

The API is under the ads namespace in the player instance. It provides the following methods, properties and events:

Methods

Properties

Events

Event constants can be found under flowplayer.ads.events.

Events can be listened to under the ads namepsace in the player instance.

Example:

player.ads.on(flowplayer.ads.events.AD_REQUEST_ERROR, function(details) {
  console.log('ad request error, reason', details.reason)
})

An example usage of IMA_BEFORE_ADS_REQUEST to set the forceNonLinearFullslot option might look like:

player.on(flowplayer.ads.events.IMA_BEFORE_ADS_REQUEST, (e)=> {
  const req = e.data.request
  req.forceNonLinearFullslot = true
})

An example usage of the IMA_ADS_RENDERING_SETTINGS to set the maximum bitrate would look like:

player.on(flowplayer.ads.events.IMA_ADS_RENDERING_SETTINGS, (e)=> {
  const renderSettings = e.data
  renderSettings.bitrate = 1024 * 10 // 10kbs
})

async adTag loading

If you intend to load adTags asynchronously through the API, you'll have to implement a fetcher function returning a new Promise and pass this to the player in the ima: configuration object.

The code might look like this:

<script type="text/javascript">
// a basic asynchronous adTag fetcher
// can be integrated with any ad bidding systems
// must always return `Promise<string>` where  string` contains the async adTag

function asyncAdTagFetcher () {
  return new Promise(function(resolve, reject) {
		resolve("https://adserver.adcompany.com/pathto/adtag_vast.xml")
	})
}

//init player
  var fpInstance = flowplayer('#player_container', {
    src: "https://some.domain.com/pathto/media.mp4",
    autoplay: true,    
    token: '<your token>',
    ima: { preload: true
    ads: [{ time: 0
            // use the async fetcher to resolve the adTag
          , adTag: asyncAdTagFetcher
          }]
  }
  });
</script>

You can find another example in our prebid.js Codepen.

Macros

To help your ad server deliver better ads for your customers you can pass metadata along with the ad request to the ad server.

Metadata is transferred to the ad server in the ad tag url by replacing pre-defined placeholders with configured values.

For instance, https://myadserver.com/ad?gender=[gender]&age=[age] with parameters { gender: 'male', age: 25 } would get translated into https://myadserver.com/ad?gender=male&age=25.

We offer several built-in macros, which are available everywhere, including self-hosted content.

Built-in macros

These macros are available for self-hosted content.

Custom macros

There are two ways of passing your custom parameters to an Ad depending on development needs.

Via the advanced js api:

  const video = flowplayer(
    { src: "f576651c-4cc6-4664-84fa-bb3b35ef1aba"
    , ima: { ads: [{time: 0, adTag: adTag}]
           , parameters: {age: 25, location: "us"}
           }
    })

Or, via the __flowplayerAdParameters magic global:

window.__flowplayerAdParameters =
  { age      : 25,
  , location : "us"
  }

The __flowplayerAdParameters global can be mutated and the mutations will propogate to the next ad call. This exposes an easy interface for dynamically synchronizing parameters over time.

Waterfalling

Waterfalling is the idea that if one ad network cannot provide a valid slot, a fallback network is then checked for a second best offering, and so on. Our ad plugin offers a simple setup of this feature to maximize revenue.

When configurating the ima.ads property, if an adTag is an Array<string>, it will assume that the adTags are an ordered list of waterfall ad providers.

Here is an example:

  const video = flowplayer(
    { src: "f576651c-4cc6-4664-84fa-bb3b35ef1aba"
    , ima: { ads: [
               { time  : 0
               , adTag : [ "https://ads.network1.com/top_choice.xml"
                           // this ad network will only be tried
                           // if the first adTag fails to fill the slot
                         , "https://ads.network2.com/waterfall_1.xml"
                         ]
               }]
    })

IMA settings

It is possible to manually set any of the IMA SDK settings by passing the name of the method without the set prefix.

For example, to set the locale you would pass Locale which will be detected internally and proxied to the setLocale() method.

Here is a complete code sample:

const video = flowplayer(
    { src: "f576651c-4cc6-4664-84fa-bb3b35ef1aba"
    , ima: { ads: [{time: 0, adTag: adTag}]
           , Locale: "en"
           , NumRedirects: 3
           }
    })

Please note that when an option is an internal IMA setting, it will begin with an uppercase letter like CookiesEnabled.

Outstream ads

Outstream ads are video ads that unroll and display advertising to a reader mid-read during text content. They are called "Outstream" because the advertising content exists outside of a normal content video lifecycle. As the user scrolls down the page, when the Outstream player comes into view, it will unfold and attempt to play the ad.

Our ad plugin supports graceful fallback to muted autoplay when autoplay with audio is not supported, on devices/browsers that allow autoplaying video content. When autoplay is not allowed, it will also gracefully handle the error.

Here is an example ima configuration option that would enable an Oustream ad:

ima: {
	ads: [
		// must be in preroll position
		{"time": 0
		// your ad tag
		,"adTag":"your.ads.com/vast.xml"
		// mark that this ad is outstream.
		,"outstream":true
		}
	]
}

Please also check the outstream ads demo.

Common outstream questions

1. Can I enable unmute on hover?
   • It is not possible to safely do this. The onmouseenter event is not considered a trusted user-gesture for the purposes of toggling audio on during video playback.
2. What happens if a user scrolls by an ad?
   • Once an ad is more than 50% outside of the viewport along the y-axis, the Outstream ad will pause playback.

Demo

Codepen

Helpful hints

• You can test your adTags in our Ad tester tool and in the Google video suite inspector .
• Make sure you use https ad tags as http links on an https website will fail.

Device support

Ads are currently not supported on Samsung Smart TVs and in the facebook in-app browser.