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 ad insertion, such as:

  • Inserting ads at the server level 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 and with Yospace.

Before you start

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

  • Access to an Ad Manager 360 Advanced account.
  • An additional contract with Google to enable DAI.

Install the plugin

To install the SSAI plugin, include the plugin script next to the core player:

Copy
Copied
<script src="//cdn.flowplayer.com/releases/native/3/stable/flowplayer.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/ssai.min.js"></script>
<script src="//cdn.flowplayer.com/releases/native/3/stable/plugins/id3.min.js"></script>

You must load the ID3 Metadata plugin to handle timed metadata and listen to timed metadata events. For more, see Handle timed metadata in linear DAI streams.

Configure the plugin 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.

The following table outlines the required SSAI plugin configuration properties available for use with Google's IMA DAI SDK. The SSAI plugin is configured under the src namespace.

Property Required DAI solution Applies to Description
assetKey Required Full service Live stream requests Used to determine which live stream should play. The live stream request asset key identifier can be found in the DFP UI. For more, see Google's API reference.
backupStream Optional N/A Live/VOD stream requests Optional back-up stream to use in case the main stream fails to play.
contentSourceId Required Full service VOD stream requests Unique identifier for the publisher content from a CMS. To retrieve this ID in the Media RSS (MRSS) feed from Google, create the content source in your Google Ad Manager UI. Helps Google's ad serving systems associate the correct ad inventory and ad targeting criteria with the specific content being streamed. For more, see Google's API reference.
customAssetKey Required Pod serving Live stream requests The custom asset key that identifies your pod serving event in Ad Manager 360. This can be created by your manifest manipulator or third-party pod serving partner. For more, see Google's API reference.
format Required (for DASH streams) Full service/Pod serving Live/VOD stream requests The stream format to request. Accepts hls (default) and dash string values. For more, see Google's API reference.
networkCode Required Pod serving Live/VOD stream requests Network code for the publisher making the stream request. Corresponds to the network code for your Ad Manager 360 account. Helps Google's ad serving systems route ad request and responses to the correct publisher account and manage ad inventory effectively. For more, see Google's API reference.
type Required N/A Live/VOD stream requests Must be set to the google/dai type to indicate that a Google DAI stream is to be used with the SSAI plugin.
videoId Required Full service VOD stream requests Identifier for each individual video asset the Google MRSS feed uses to populate the content source library. Helps Google's ad serving systems to associate ad targeting criteria and ad insertion policies with specific videos. For more, see Google's API reference.
info

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

DAI full service example

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

VODLive stream
Copy
Copied
var player = flowplayer('#container',
    { src: [
        { contentSourceId  : "2528370",
          videoId          : "tears-of-steel",
          type             : "google/dai",
          backupStream     : "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
    }] }
  )
Copy
Copied
var player = flowplayer('#container',
    { src: [
        { assetKey      : "sN_IYUG8STe12345_ksA",
          type          : "google/dai",
          backupStream  : "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
    }] }
  )

DAI pod serving example

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

Copy
Copied
var player = flowplayer('#container',
    { src: [
        { customAssetKey  : "sN_IYUG8STe12345_ksA",
          networkCode     : "51636543",
          type            : "google/dai",
          backupStream    : "http://storage.googleapis.com/testtopbox-public/video_content/bbb/master.m3u8"
    }] }
  )

Configure the plugin 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.

Property Description
type Set to yospace to indicate that a Yospace stream is to be used with the SSAI plugin.
src Identifies the Yospace stream.

Example

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

Copy
Copied
var player = flowplayer('#container',
    { src: [
        { type  : "yospace",
          src   : "https://csm-e-sdk-validation.bln1.yospace.com/csm/access/12345/c2FtcGxlL21hc3Rl?yo.av=3"
        }
    ]}
  )

Listen to 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.

Event Description
flowplayer.ssai.events.SSAI_AD_COMPLETED Fires when an individual ad completes.
flowplayer.ssai.events.SSAI_AD_END Fires the first time each ad break ends.
flowplayer.ssai.events.SSAI_AD_START Fires the first time each ad break begins playback.
flowplayer.ssai.events.SSAI_AD_STARTED Fires when an ad starts.
flowplayer.ssai.events.SSAI_AD_PAUSED Fires when an ad pauses.
flowplayer.ssai.events.SSAI_AD_PROGRESS Fires when the current ad progresses.
flowplayer.ssai.events.SSAI_AD_RESUMED fires when an ad resumes.
flowplayer.ssai.events.SSAI_AD_SKIPPED Fires when the user skips an ad.

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:

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