Advertising plugin

The Advertising plugin allows you to seamlessly integrate various ads into your video content, including pre-roll, mid-roll, and post-roll ads. These ads can be served from different ad networks or custom ad servers.

The plugin supports industry-standard ad formats and definitions, such as Video Ad Service Template (VAST), Video Player-Ad Interface Definition (VPAID), and Video Multiple Ad Playlist (VMAP). For instance, it allows you to play video and text overlay ads from multiple VAST (versions 2, 3, or 4) and VPAID (version 2) compliant tags, or from a single VMAP/adPod tag.

View this CodePen demo to get see a simple example of how to install and configure the Advertising plugin.

Install the plugin

Load the core player and the Advertising plugin. For player 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>

Configure the plugin

You can configure the plugin manually using JavaScript. The tables in this section provide information about different configuration options and properties for the core plugin and plugin's user interface (UI).

Core plugin configuration

Ads are configured with the top level ima configuration option and the properties in the following table.

For an example, see the following JavaScript ima object configuration:

"ima": {
  // Specify array of ad objects to define the timing and ad tags
  "ads": [
    {
      // First pre-roll ad with URL to VAST XML file containing the ad info
      "time": 0,
      "adTag": "https://mydserver.com/path/vast.xml"
    },
    {
      // Second mid-roll ad at 20 seconds with URL to VAST XML file
      "time": 20,
      "adTag": "https://mydserver.com/path/vast2.xml"
    },
    {
      // Third mid-roll ad at 300 seconds with URL to VAST XML file
      "time": 300,
      "adTag": "https://mydserver.com/path/vast3.xml"
    } //ad 2: midroll at 300 seconds
  ],
  // Specify additional parameters to pass to the ad server when requesting ads
  "parameters": {
    "age": 25,
    "location": "us"
  },
  // Don't show first and second mid-roll if user seeks after 300 seconds
  "show_all_ads_on_seek": false,
  // Disable the ad indicator
  "indicator": false,
  "ui":
}

UI configuration

You can use the options in the following table to configure UI elements when an advertisement is playing.

For example, you can use this code snippet to show the ad choices logo and the ad remaining time widget when the ad plays:

flowplayer("#player", {
  src: "my_video.mp4",
  token: "[my-token]",
  ads: {
    ui: flowplayer.ads.ui.AD_CHOICES | flowplayer.ads.ui.AD_REMAINING_TIME
  },
  ima: {
    ...
  }
})

IMA settings

It's 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 can pass the Locale property which is detected internally and proxied to the setLocale() method.

Here's 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 starts with an uppercase letter like CookiesEnabled.

Manage the plugin

You can use the properties and methods described in this section to interact with our API and manage the Advertising plugin and video playback. The properties can be used to retrieve information about the current state of the plugin and to modify the plugin's behavior. The methods allow you to work with the plugin and to perform specific actions to control the plugin's behavior.

Properties

Methods

Listen to plugin events

To listen to events for this plugin, use the ads namespace with the Universal Module Definition (UMD) and the global flowplayer variable. For example, use flowplayer.ads.events to capture an event. The following tables describe the object path and events for the Advertising plugin based on type.

Ad group events

Adapter events

An example usage of the IMA_BEFORE_ADS_REQUEST event to set the forceNonLinearFullslot option looks 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 event to set the maximum bitrate looks like:

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

Or you could force a styledLinearAd with this snippet:

player.on(flowplayer.ads.events.IMA_ADS_RENDERING_SETTINGS, (ev)=> {
    ev.detail.useStyledLinearAds = true
  })

General events

HTTP events

For example, you can use this code to set up an event listener capturing when an ad request fails. Then add your custom logic inside the callback function:

player.ads.on(flowplayer.ads.events.AD_REQUEST_ERROR, function(details) {
  // Add your code here
  console.log("ad request error, reason", details.reason)
})

Timing events

UI type events

Pass metadata with 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.

Built-in macros

We offer several built-in macros, which are available everywhere, including with self-hosted content. 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. The first method uses the advanced JavaScript API, as in this example:

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

The second method uses the __flowplayerAdParameters magic global:

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

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

Apply ad 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 configuring the ima.ads property, if an adTag is an Array<string>, the player assumes the adTags are an ordered list of waterfall ad providers:

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

Enable outstream ads

Outstream ads are video ads that unroll and display advertising to a reader mid-read during text content. They're called outstream because the advertising content exists outside the typical 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 isn't supported on devices or browsers that allow auto-playing video content. When autoplay isn't allowed, it gracefully handles the error.

Here is an example ima configuration that enables an outstream ad:

ima: {
  ads: [{
    // Must be in pre-roll position
    "time": 0,
    // Your ad tag
    "adTag": "your.ads.com/vast.xml",
    // Mark this ad is an outstream ad
    "outstream": true
  }]
}

Please also check the outstream ads demo.

Common outstream questions

Configure Prebid header bidding

Prebid.js is an open-source JavaScript framework designed to implement header bidding. This technique allows publishers to auction off their ad inventory in real-time to multiple ad exchanges before making ad calls to their ad server. Publishers can consequently improve ad quality on their websites while reducing latency between bid requests and responses. They can also maximize ad revenue by creating a more competitive environment for ad placements. To learn more, see how Prebid.js works.

With the Advertising plugin, you can configure the player to leverage the Prebid.js library and header bidding directly.

Prebid properties

We support multiple providers in one configuration for instream ads. However, required parameters vary across bidders. To understand what parameters are necessary for your configuration, make sure to search for your provider and to follow the Prebid.js documentation. To reduce complexity, we also recommend using a wrapper like the Livewrapped adapter.

This table outlines parameters you can use to configure our player with your Prebid.js integration. For a sample implementation, see our Prebid.js header bidding developer demo.

Use async adTag loading

If you intend to load adTags asynchronously through the API, you must implement a fetcher function returning a new Promise and pass this to the player in the ima: configuration object, as in the following example:

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

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