Server-Side Ad Insertion (SSAI) plugin

The SSAI plugin allows you to serve ads that are dynamically inserted into video content at the server level before content is delivered to the viewer's device. This is in contrast to client-side ad insertion (CSAI), where the viewer's device inserts ads during playback. Ad insertion on the server side is typically in real-time or near real-time. SSAI offers several advantages over CSAI, such as:

• Server-level ad insertion makes advertisements less susceptible to ad blockers used by viewers, resulting in higher delivery rates.
• SSAI allows for more precise ad targeting based on real-time viewer data, leading to higher ad relevance and engagement.
• Ads are seamlessly integrated into the video stream. Therefore, viewers experience smooth playback without buffering or quality degradation during ad transitions.

The SSAI plugin can be configured to work with Google's Interactive Media Ads Dynamic Ad Insertion (IMA DAI) SDK, with AWS Elemental MediaTailor, and with Yospace.

Before you start

Before you use this plugin with the standalone player, we recommend the following steps:

• Read about embedding the core player in your site by adding the minimum CSS and JavaScript player components.
• Make sure you have a player token. For more see, Token configuration . Tokens aren't needed for local development.
• The instructions on this page generally assume you're using the Wowza Flowplayer CDN to embed the player in your site. If you're using npm, see our npm instructions or our TypeScript guide .

DAI considerations

For Google's IMA DAI integration to work with the SSAI plugin, consider the following before you start:

• Access to a Google Ad Manager 360 Advanced account and a contract with Google to enable DAI.
• To use IMA DAI pod serving, you must be working with a pod-serving partner.

MediaTailor considerations

For MediaTailor integrations to work with the SSAI plugin, consider the following before you start:

• See this AWS Elemental MediaTailor guide to get started in AWS.
• If configuring with your own MediaTailor stream and not Wowza Video media, review Enabling ad ID signaling for sessions . You must add the aws.adSignalingEnabled=true query parameter to your MediaTailor HLS URL for the configuration to work.
• If configuring with Wowza Video media, load the Wowza Video Platform Integration plugin as well. See Set up an SSAI schedule in Wowza Video for more details.

Install the plugin

To install the SSAI plugin, load it next to the core player:

<!-- Load standard player skin -->
<link rel="stylesheet" href="https://cdn.flowplayer.com/releases/native/3/stable/style/flowplayer.css">
<!-- Load player script -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>

<!-- Load plugin -->
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/ssai.min.js"></script>

// Import player library and basic CSS for player
import flowplayer from "@flowplayer/player";
import "@flowplayer/player/flowplayer.css";

// Import plugin
import SSAI from "@flowplayer/player/plugins/ssai";

Add HTML elements

Add the HTML components to render the player elements on your page:

<div id="player"></div>

Configure with MediaTailor

You can configure the SSAI plugin for use with the Wowza Flowplayer and the AWS Elemental MediaTailor ad insertion service that runs in the AWS Cloud. Our MediaTailor integration supports Apple HTTP live Streaming (HLS) for video on demand (VOD) workflows and linear ads. The configuration with the player can point to your own MediaTailor stream or a Wowza Video media asset.

The following table outlines the required SSAI plugin configuration properties to set up the standalone player with your own AWS Elemental MediaTailor stream. The SSAI plugin is configured under the src namespace.

Example

The following example demonstrates how to configure the player with the properties for your MediaTailor stream. You can also see how to add MediaTailor macros to pass custom metadata along with the ad request to the ad server. Replace placeholder values with your own.

const player = flowplayer("#player", {
  title: "MediaTailor stream configuration",
  token: "[your-player-token]",
  src: {
    type: "mediaTailor",
    // Replace with source URL for your MediaTailor stream
    stream: "[mediaTailor-source-url]?aws.adSignalingEnabled=true",
    // Add custom parameters to pass MediaTailor macros
    parameters: {
      age: 25,
      location: "us"
    }
  }
});

For more information about using built-in and custom macros, see Pass metadata with macros.

Configure with DAI

You can configure the SSAI plugin for use with the Google IMA DAI SDK, allowing for the seamless integration of server-side ad stitching techniques. The IMA DAI SDK returns a combined video stream, so you don't have to manage switching between ad and video content within your application. We support both of Google's Full service and Pod serving DAI solutions.

The tables in this section outline the SSAI plugin configuration properties available when configuring the player with Google's IMA DAI SDK. The SSAI plugin is configured under the src namespace.

In addition to the mentioned properties, the SSAI plugin supports all stream request properties available with Google IMA DAI SDK. For a full list, see these references:

• Full service live - LiveStreamRequest class
• Full service VOD - VODStreamRequest class
• Pod serving live - PodStreamRequest class
• Pod serving VOD - PodVodStreamRequest class

You can use these Google IMA sample streams when testing streams with your workflows.

DAI VOD stream parameters

These properties can be used when configuring the player with a DAI VOD stream request.

Example

The following example demonstrate how to incorporate a request for VOD assets using the DAI full-service solution. Aside from the type property, values in these examples are placeholders and must be replaced with your own.

const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: [{
    contentSourceId: "2548831",
    videoId: "tears-of-steel",
    type: "google/dai",
    backupStream: "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
  }]
});

// SSAI plugin uses networkCode to generate VOD pod serving request
// When DAI stream is initialized, SSAI plugin gets stream ID from IMA DAI SDK
// Stream ID is then passed as argument to requestStreamUrl function

const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: [{
    requestStreamUrl: (streamManager, streamId) => {
      // Add your code to get stream URL from your VTP
    },
    networkCode: "51636543",
    type: "google/dai",
    backupStream: "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
  }]
});

DAI live stream parameters

These properties can be used when configuring the player with a DAI live stream request.

Example

The following examples demonstrate how to incorporate a request for live stream assets using the DAI full-service and pod-serving solutions. Switch between the Live full service and Live pod serving tabs to see code snippets for using the player in each scenario. Aside fom the type property, values in these examples are placeholders and must be replaced with your own.

const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: [{
    assetKey: "c-rArva4ShKVIAkNfy6HUQ",
    type: "google/dai",
    backupStream: "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
  }]
});

const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: [{
    customAssetKey: "google-sample",
    streamUrl: "https://encodersim.sandbox.google.com/masterPlaylist/9c654d63-5373-4673-8c8d-6d92b66b9d46...&stream_id=[[STREAMID]]",
    networkCode: "51636543",
    type: "google/dai",
    backupStream: "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
  }]
});

Configure with Yospace

You can configure the SSAI plugin to use with Yospace's DAI for live and VOD content. The following table outlines SSAI plugin configuration properties available for use with Yospace. The SSAI plugin is configured under the src namespace.

Example

In the following example, replace the src value with your own Yospace stream.

const player = flowplayer("#player", {
  token: "[your-player-token]",
  src: [{
    type: "yospace",
    src: "https://csm-e-sdk-validation.bln1.yospace.com/csm/access/12345/c2FtcGxlL21hc3Rl?yo.av=3"
  }]
});

Listen to plugin events

This section describes the events you can capture to control and manage SSAI events within your player instance. To understand even handling differences between CDN and npm implementations, see Plugin events.

To listen to events for this plugin, use the ssai namespace in the player instance. For example, use flowplayer.ssai.events to capture an event. The following table describes the object path and events for the SSAI plugin.

For example, use the following code to set up an event listener capturing when a server-side ad is paused. Then add your custom logic inside the callback function:

player.on(flowplayer.ssai.events.SSAI_AD_PAUSED, (event) => {
  // Add your code here
  console.log("Server-side ad paused.");
});

player.on(SSAI.events.SSAI_AD_PAUSED, (event) => {
  // Add your code here
  console.log("Server-side ad paused.");
});