Skip to content

Advertisement Insertion

On this page:

  1. Description
  2. Aspects of ad insertion in Flussonic
  3. Flussonic ad insertion mechanisms
  4. How to configure advertisement insertion with auth backend
    1. Lua example
    2. HTTP auth backend example

Description

Flussonic allows you to embed ads (commercials) in play sessions and configure the display of the ads through the authorization backend.

You can:

1) specify a pre-roll video,

2) set an interval for inserting mid-roll videos,

3) specify ads that are unique for each user/view.

Aspects of ad insertion in Flussonic

It is necessary to preprocess the ad clips before using them in ad insertion in Flussonic. Here are a few aspects and requirements to consider:

  • Main stream and advertisement stream characteristics (media_info) must be identical. Otherwise, Flussonic ignores the ad stream and will not perform the ad insertion.

  • An advertising video must have a GOP size equal to one second.

  • HLS players usually skip the first 1-5 seconds of the pre-roll video (it is the feature of HLS players). However, adding black frames in the beginning of the video solves the issue.

  • Plugins such as AdBlock block the commercials. If something goes wrong, try disabling the plugins.

Flussonic ad insertion mechanisms

There are two ad insertion mechanisms in Flussonic. The second one is the upgraded version of the first one.

The mechanism of ad insertion itself is an extension of the authorization system, so please read the documentation on it first. It works with HLS and DASH protocols. So to play the stream with embedded advertising clips, you should access it over HLS or DASH. Otherwise, it will not work.

The first mechanism is used by default.

The second ad insertion mechanism complicates the work of ad blockers. It replaces the stream segments within the play session so that it is impossible to distinguish whether it is a main stream segment or an ad segment. It also allows you to customize the advertisements for a particular user. Besides, it works with a single-period as well as a multi-period DASH.

You can enable the mechanism adding the v=2 parameter in the ad_inject section of the auth backend response. (See the Lua and PHP examples).

Here is an example of the URL for an HLS main stream segment compared to the URL of an ad segment:

HLS main stream segment URL http://FLUSSONIC-IP/STREAM_NAME/tracks-v1a1/2021/09/28/09/27/25-05000.ts?token=adv2user-12312324342
Ad segment URL http://FLUSSONIC-IP/STREAM_NAME/tracks-v1a1/2021/09/28/09/27/30-05000.ts?token=adv2user-12312324342

Both mechanisms require the above-mentioned requirements to be met.

Danger

You must use files with advertisement videos that are located in configured VOD locations on the Flussonic server. Don't specify a path to the local file system or an HTTP source. It is critical to create a VOD location and place the files there.

How to configure advertisement insertion with auth backend

To configure advertisement insertion with auth backend:

1) Choose the programming language option that suits you best: Lua или PHP.

2) Configure a VOD location and place the ad videos there.

Warning

Make sure your advert videos meet the requirements.

3) Add the location of the clips to your script.

4) Configure the stream adding the auth directive with a path to the script to the configuration file:


stream example_stream {
  url fake://;
  auth ad2.lua;
}
file ad_vod {
  path /storage;
}

5) Ensure that it works by playing the stream over HLS/DASH.

Lua example

The auth backend should return this structure to start the advertising:

  • Option 1 (the first mechanism):

user_ads = {
      ['preroll'] = 'ad_vod/preroll1.mp4',
      ['midroll_interval'] = 180,
      ['midroll'] = {'ad_vod/midroll1.mp4','ad_vod/midroll2.mp4'}
    }
    return true, {['ad_inject'] = user_ads}

  • Option 2 (the second mechanism with v=2 parameter):

user_ads = {
      ['v'] = 2,
      ['preroll'] = 'ad_vod/preroll1.mp4',
      ['midroll_interval'] = 180,
      ['midroll'] = {'ad_vod/midroll1.mp4','ad_vod/midroll2.mp4'}
    }
    return true, {['ad_inject'] = user_ads, auth_time = 30}

Flussonic will show the file ad_vod/preroll1.mp4 as pre-roll and then show mid-roll files every 3 minutes (180 seconds). It checks the backend overy 30 seconds (auth_time = 30) to see if any updates were made.

HTTP auth backend example

Here are the examples of a PHP auth script for ad insertion:

  • Option 1 (the first mechanism):

<?php

header('Content-type: application/json');

$user_ads = [
    "preroll" => "ad_vod/preroll1.mp4",
    "midroll_interval" => 180,
    "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"]
];

echo json_encode(array("ad_inject" => $user_ads));
?>

  • Option 2 (the second mechanism with v=2 parameter):

<?php

header('Content-type: application/json');

$user_ads = [
    "v" => 2,
    "preroll" => "ad_vod/preroll1.mp4",
    "midroll_interval" => 180,
    "midroll" => ["ad_vod/midroll1.mp4", "ad_vod/midroll2.mp4"]
];

echo json_encode(array("ad_inject" => $user_ads));
?>

Flussonic Media Server will show the file ad_vod/preroll1.mp4 as pre-roll and then show mid-roll files every 3 minutes (180 seconds).