Overview

With ad rules, you can adapt the frequency and size of ad breaks to the content duration. For example, you can apply different sets of rules for short and long content.

Declare ad rules

General structure

Ad rules are an array of objects. Based on the content’s duration, the Video plugin will select the appropriate object (ad rule).

Each ad rule contains the following properties:

• duration_min and duration_max: The duration of the content the ad rule applies to.
• data: The number of instances (video ads) and the maximum ad pod duration
• minimumDelayBetweenAdBreaks: An optional property to enforce a minimum duration (in seconds) between two linear ad breaks.

The following example shows ad rules that are applied based on the content duration. For example, the first ad rule is applied if the content duration is 0 seconds to 120 seconds long.

[
   {
       "duration_min": 0,
       "duration_max": 120,
       "data": {
           ...
       }
   },{
       "duration_min": 120,
       "duration_max": 600,
       "data": {
           ...
       },
       "minimumDelayBetweenAdBreaks": 180
   },{
       "duration_min": 600,
       "duration_max": 3600,
       "data": {
           ...
       },
       "minimumDelayBetweenAdBreaks": 600
   },{
       "duration_min": 3600,
       "duration_max": -1,
       "data": {
           ...
       },
       "minimumDelayBetweenAdBreaks": 1800
   }
]

Ad rule data

The data of an ad rule contains the configuration for different ad break types (pre-roll, mid-roll, post-roll, overlay)

The instances property is required within each ad break type object, such as prerolls, or midrolls, and controls whether the ad break type is enabled and how many ads are expected:

• 0: The ad break type is disabled.
• A positive integer: The ad break type is enabled. This value explicitly sets the number of expected ads for this ad break, overriding any number defined in the format ID in the Equativ Monetization Platform.

The following applies, if an entire ad break section is omitted in the data object:

• midrolls and overlays: omitting the section disables the ad break, which is equivalent to setting "instances": 0. For overlays, the maximum allowed value for instances is 1.
• prerolls and postrolls: omitting the section enables the ad break, which is equivalent to setting "instances": 1.

To explicitly disable pre-rolls or post-rolls, you must include the section and set "instances": 0.

The maxAdPodDuration property is used for pre-roll, mid-roll, or post-roll ad breaks. It defines the maximum total duration of an ad pod, measured in seconds. Its value must be a positive integer. If the property isn't defined, or its value is 0 or a negative integer, maxAdPodDuration isn't taken into account by ad rules.

The following example shows an ad rule data object with sections for each ad break type.

"data": {
    "prerolls": {
        "instances": 1,
        "maxAdPodDuration": 25
        (...)
    }, 
    "midrolls": {
        "instances": 0,
        (...)
    },
    "postrolls": {
        "instances": 1,
        (...)
    },
    "overlays": {
        "instances": 1,
        (...)
    }
}

Integrate ad rules

You can define the ad rules for your video player using an external JSON file or by passing them directly in the player configuration.

Use external JSON file

To use an external JSON file, provide the file's URL in the adRules property when registering your player:

sas.video.register({
    id: 'myContainer',
    adData: {...},
    adRules: 'url_to_ad_rules_file.json',
    ...
});

The Video plugin uses an AJAX request to load your external ad rules file. To ensure the plugin can read the file, the server hosting the file must return the following Cross-Origin Resource Sharing (CORS) headers in its response:

Access-Control-Allow-Origin: http://yourdomain.com*
Access-Control-Allow-Credentials: true

Replace yourdomain.com by the domain containing the Video plugin.

Sending CORS headers isn't required if you meet either of these conditions:

• The external adRules JSON file is hosted on the same domain as the website containing the Video plugin.
• You pass the adRules directly as an array of objects.

The following example shows how to pass the ad rules directly as an array of JSON objects to the adRules property:

sas.video.register({
    id: 'myContainer',
    adData: {...},
    adRules: [{...}, {...}, {...}],
    ...
});

Default ad rule

The following code block shows the default ad rule, applied to any content duration:

[{
   "duration_min": 0,
   "duration_max": -1,
   "data": {
       "prerolls": {
           "instances": 1,
           "maxAdPodDuration": 0
       },
       "midrolls": {
           "instances": 0,
           "maxAdPodDuration": 0,
           "percents": [],
           "interval": 0,
           "timecodes": []
       },
       "postrolls": {
           "instances": 1,
           "maxAdPodDuration": 0
       },
       "overlays": {
           "instances": 0,
           "percents": [],
           "interval": 0,
           "timecodes": []
       }
   }
}]

Control ad break timing and duration

You can configure several properties within your ad rules to control when ad breaks appear and how long they last. These properties apply to linear ad breaks (pre-roll, mid-roll, and post-roll) and overlays.

Set minimum delay between ad breaks

Use the optional minimumDelayBetweenAdBreaks property to enforce a minimum duration (in seconds) between two consecutive linear ad breaks per user. This prevents mid-roll ad breaks from launching repeatedly when a user seeks within the content.

The value must be a positive number, expressed in seconds (default value: 0).

The following example shows a minimum delay of 600 seconds (10 minutes) between ad breaks.

{
    "duration_min": 0,
    "duration_max": 3600,
    "data": {
        (...)
    },
    "minimumDelayBetweenAdBreaks": 600
}

Set maximum ad pod duration

Optionally, you can define a maximum ad pod duration for each ad break type (pre-roll, mid-roll, post-roll).

Add the maxAdPodDuration property to the relevant ad break configuration, and set a positive number of seconds.

You must also define the instances property, which specifies the number of ads the Video plugin attempts to retrieve. Set the value of instances high enough to retrieve many ads with different durations. The Video plugin selects a subset of these ads to compile the ad pod and comply with the specified maximum ad pod duration. Example: maxAdPodDuration / 20 < instances.

The following example shows a maximum ad pod duration of 75 seconds and four ad instances for the pre-roll ad break. 

"prerolls": {
    "instances": 4,
    "maxAdPodDuration": 75
}

Configure mid-roll ad breaks

Mid-roll ads are linear ad breaks that occur during content playback. You can specify the timing of these breaks using one of three parameters: percents, interval, or timecodes. Note that pre-rolls and post-rolls only have one ad break each, while mid-rolls can have multiple.

Percents

You can define the position of mid-roll breaks as an array of percentages of the content duration. The values must be numbers between 0 and 100.

The following example shows two mid-roll ad breaks, at 33% and 66% of the content duration. The Video plugin will attempt to display four linear ads in a row for each break.

"midrolls": {
    "instances": 4,
    "percents": [33, 66]
}

Interval

You can use the interval parameter to specify a fixed duration (in seconds) between mid-roll ad breaks. This parameter is only taken into account if percents isn't defined.

The following example shows an interval of 900 seconds (15 minutes). If the content was 55 minutes long, three mid-roll ad breaks would be inserted: at 15, 30, and 45 minutes. In each ad break, the Video plugin will attempt to display five linear ads in a row:

"midrolls": {
    "instances": 5,
    "interval": 900
}

When using interval, you can optionally define the offset parameter to set the position of the first mid-roll ad break. The value must be a duration, expressed in seconds. By default, offset equals interval.

The following example shows an interval of 900 seconds (15 minutes) and an offset of 300 seconds (5 minutes). If the content was 55 minutes long, four ad breaks would be inserted: at 5, 20, 35, and 50 minutes. In each ad break, the Video plugin will attempt to display five linear ads in a row:

"midrolls": {
    "instances": 5,
    "offset": 300,
    "interval": 900
}

Timecodes

You can use the timecodes parameter to specify the exact positions of mid-roll ad breaks as an array of timecode strings. This parameter is taken into account only if the percents and interval parameters aren't defined.

Supported timecode formats include the following:

• HH:MM:SS.mmm
• HH:MM:SS
• MM:SS.mmm
• MM:SS
• SS.mmm
• SS

The following example shows three mid-roll ad breaks, inserted at 15 s, 90.5 s, and 5400 s (1 hour 30 minutes). In each ad break, the Video plugin will attempt to display five linear ads in a row:

"midrolls": {
    "instances": 5,
    "timecodes": ['00:00:15', '01:30.500', '01:30:00.000']
}

Configure overlays

Overlays are non-linear ads that appear on top of the content video. Like mid-rolls, you can specify the timing of these overlays using one of three parameters: percents, interval, or timecodes.

Percents

You can define the position of overlays as an array of percentages of the content duration. The values must be numbers between 0 and 100.

The following example shows two overlays, at 33% and 66% of the content duration:

"overlays": {
    "instances": 1,
    "percents": [33, 66]
}

Interval

You can use the interval parameter to specify a fixed duration (in seconds) between the overlays. This parameter is only taken into account if percents isn't defined.

The following example shows an interval of 900 seconds (15 minutes). If the content was 55 minutes long, three overlays would be inserted: at 15, 30, and 45 minutes:

"overlays": {
    "instances": 1,
    "interval": 900
}

When using interval, you can optionally define the offset parameter to set the position of the first overlay ad. The value must be a duration, expressed in seconds. By default, offset equals interval.

The following example shows an interval of 900 seconds (15 minutes) and an offset of 300 seconds (5 minutes). If the content was 55 minutes long, four overlays would be inserted: at 5, 20, 35, and 50 minutes:

"overlays": {
    "instances": 1,
    "offset": 300,
    "interval": 900
}

Timecodes

You can use the timecodes parameter to specify the exact positions of overlays as an array of timecode strings. This parameter is taken into account only if the percents and interval parameters aren't defined.

Supported timecode formats include the following:

• HH:MM:SS.mmm
• HH:MM:SS
• MM:SS.mmm
• MM:SS
• SS.mmm
• SS

The following example shows three overlays, inserted at 15, 90.5, and 5400 seconds (1 hour 30 minutes):

"overlays": {
    "instances": 1,
    "timecodes": ['00:00:15', '01:30.500', '01:30:00.000']
}

Ad rules for live content

The duration of live content is unknown. Therefore, the duration_max must be set to -1. 

For pre-rolls and mid-rolls, you can define the ad break size (number of video ad instances) as for normal content. However, make sure you use the interval property to define mid-roll positions. The percents and timecodes methods don't work for live content.
For live content, post-rolls aren't supported.

The following example shows the duration_max property set to -1,

[
   {
       "duration_min": 0,
       "duration_max": -1,
       "data": {
           ...
       }
   }
]

Manage ad breaks with server-side ad rules

You can create server-side ad rules in the Equativ Monetization Platform (EMP). For more information, see Set video ad rules.

To use server-side ad rules, you must activate server-side ad rules in the publisher section of your ad plugin configuration and set up the server-side ad rules in EMP.

When you enable server-side ad rules, the ad responses will be based on the server-side ad rules: in response to each call, the specific number of ads defined in EMP are returned for that ad break. Alternatively, a noad response is returned if no ads are specified for the corresponding ad break.

Ad rules example

The following example shows a complete set of ad rules. You can use it as a template to build your own JSON file/object passed to the sas.video.register method:

[
    {
        "duration_min": 0,
        "duration_max": 120,
        "data": {
            "overlays": {
                "instances": 1,
                "interval": 30,
                "offset": 10
            }
        }
    },
    {
        "duration_min": 120,
        "duration_max": 3600,
        "data": {
            "prerolls": {
                "instances": 1,
                "maxAdPodDuration": 75
            },
            "midrolls": {
                "instances": 3,
                "percents": [50],
                "interval": 0
            },
            "postrolls": {
                "instances": 1,
                "maxAdPodDuration": 50
            },
            "overlays": {
                "instances": 1,
                "interval": 30,
                "offset": 10
            }
        },
        "minimumDelayBetweenAdBreaks": 300
    },
    {
        "duration_min": 3600,
        "duration_max": -1,
        "data": {
            "prerolls": {
                "instances": 4
            },
            "midrolls": {
                "instances": 3,
                "maxAdPodDuration": 60,
                "percents": [20, 40, 60, 80],
                "interval": 0
            },
            "postrolls": {
                "instances": 2
            },
            "overlays": {
                "instances": 1,
                "interval": 30,
                "offset": 10
            }
        },
        "minimumDelayBetweenAdBreaks": 1800
    }
]