Ad Rules

Structure

Ad rules is a set of arrays of objects. The plugin will select the right object (ad rule) based on the content's duration. To achieve this, each ad rule must contain 2 properties: duration_min and duration_max. Each ad rule must also include a data property. Additionally, you can also include the minimumDelayBetweenAdBreaks property to enforce a minimum duration (in seconds) between two linear ad breaks for a given user in a given content video.

Sample of a valid ad rules JSON:

[
    {
        "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
    }
]
		

In this sample, if the content's duration is:

• between 120 seconds (inclusive) and 600 seconds, the second ad rule will be applied;
• exactly 600 seconds, the third ad rule will be applied;
• longer than or equal to 1 hour, the last ad rule will be applied.

Here is the structure of the data of an ad rule. For each ad break type, it contains nested related objects:

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

For each ad break type object, an instances property is expected:

• 0 - this type of ad break is disabled;
• a positive integer - this type of ad break is enabled and the expected number of ads for such breaks will be set to this value, regardless of what was defined in Manage for the related format ID.

The maxAdPodDuration property for preroll, postroll and midroll ad breaks represents the maximum duration of an ad pod (in seconds). Its value should be a positive integer. If this property is not defined or the value is equal to 0 or to a negative integer, maxAdPodDuration is not taken into account in ad rules.

Integration

Ad rules can be defined in an external file in the JSON format. It is an array of objects described below. When registering your player, add an adRules section in the configuration object:

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

You can also pass an array of objects to this method:

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

Required settings for the loading of the adRules-file

Equativ's plugin will try to load your file with AJAX. To ensure the plugin can read the file content, make sure that your response contains CORS headers as follows:

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

*yourdomain.com - your domain, where Equativ's plugin is integrated

Note: Sending CORS headers is not needed in case your adRules are directly passed as an array of objects or in case the adRules-file is loaded from the domain of your website (where Equativ's plugin is integrated).

Default ad rules

By default, only one ad rule is defined. It will apply 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": []
        }
    }
}]
		

Specific parameters

Minimum delay between ad breaks

For each ad rule, you can define a minimumDelayBetweenAdBreaks property: this enforces a minimum duration (in seconds) between two linear ad breaks for a given user in a given content video; it is used to prevent launching midroll ad breaks in a loop while seeking into the content. The value of the property should be a positive number in seconds:

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

By default, minimumDelayBetweenAdBreaks is equal to 0 and it is not mandatory to have it in an every ad rule.

AdPod duration

You can define a maximum ad pod duration for preroll, midroll and postroll (not used by default). To enable it for a given ad break type, add the property maxAdPodDuration to the configuration. The value of the property should be a positive number, expressed in seconds:

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

Make sure you define the instances property as well. The number of instances should be high enough to retrieve many ads with different durations, from which the Plugin can select the best durations to compile the ad pod and comply with the specified ad pod duration. Example:
maxAdPodDuration / 20 < instances
There is no guarantee that all returned ads will be displayed (usually, the plugin selects a subset to fill the ad break).
The plugin will take the real playback duration into account - when a user skips after a few seconds, only those seconds are counted.

Midrolls

Obviously, there is only one ad break for prerolls and one for postrolls. But there can be several midroll ad breaks. 3 parameters can be used to determine this number of midroll ad breaks: percents, interval or timecodes.

If the percents parameter is defined, it should be an array of numbers between 0 and 100. In the following example, there will be 2 midroll ad breaks. One at 33% and one at 66% of the content duration. For each ad break, the plugin will try to display 4 linear ads in a row:

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

If the interval parameter is defined, it should be a duration, indicated in seconds. For this parameter to be taken into account, the percents parameter should not be defined. In the following example, if the content is 55 minutes long, a midroll ad break is displayed every 900 seconds (15 minutes). There will be 3 ad breaks: when the content reaches 15 minutes, 30 minutes and 45 minutes. For each ad break, the plugin will try to display 5 linear ads in a row:

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

When an interval parameter is used, it is also possible to define the offset parameter. It must be a duration, expressed in seconds. It describes the position of the first midroll ad break. By default, offset is equal to interval. In the following example, if the content is 55 minutes long, there will be a midroll ad break every 900 seconds (15 minutes), the first midroll ad break will be executed after 5 minutes. There will be 4 ad breaks: when the content reaches 5 minutes, 20 minutes, 35 minutes and 50 minutes. For each ad break, the plugin will try to display 5 linear ads in a row:

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

If the timecodes parameter is defined, it should be an array of timecode strings. Possible formats are:

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

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

If the content is a live stream, only the interval parameter is taken into account.

Important: While using the Equativ Video Plugin for HTML5 players, midroll ad breaks can only be activated if the integration can ensure a seamless fullscreen experience between content and ads. In that case, the publisher needs to set the configuration parameter html5SeamlessFullscreen to "true" in the plugin configuration; otherwise, midroll ad breaks will not be enabled even if they are defined in the ad rules setup.

Overlays

As for midrolls, 3 parameters can be used to determine the number of overlay ad breaks: percents, interval or timecodes.

If the percents parameter is defined, it should be an array of numbers between 0 and 100. In the following example, there will be 2 overlay ad breaks: one at 33% and one at 66% of the content duration:

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

If the interval parameter is defined, it should be a duration, expressed in seconds. For this parameter to be taken into account, the percents parameter should not be defined. In the following example, if the content is 55 minutes long, there will be an overlay ad break every 900 seconds (15 minutes). There will be 3 ad breaks: when the content reaches 15 minutes, 30 minutes and 45 minutes:

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

When an interval parameter is used, it is also possible to define the offset parameter. It must be a duration, expressed in seconds. It describes the position of the first overlay ad break. By default, offset is equal to interval. In the following example, if the content is 55 minutes long, there will be an overlay ad break every 900 seconds (15 minutes), the first overlay ad break will be executed after 5 minutes. There will be 4 ad breaks: when the content reaches 5 minutes, 20 minutes, 35 minutes and 50 minutes:

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

If the timecodes parameter is defined, it should be an array of timecode strings. Possible formats are:

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

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

If the content is a live stream, only the interval parameter is taken into account.

Note: for overlays, the maximum possible value of the instances parameter is 1.

Live Content rules

Since the content duration is not known in live streams, the structure of ad rules looks as follows:

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

The property duration_max must be set to -1.

For prerolls and midrolls, you can define the ad break size (instances) as for normal content; however, make sure you use the interval property to define midroll positions. The percents and timecodes will not work for live content.
Note: For live content, postrolls are not supported.

Server-side ad rules

You can also use Server-side ad rules to manage your ad breaks.

In Equativ Adserver UI, you are able to define Ad rules with targeting criterias that will then be applied to display ad breaks for your content.

To leverage server-side ad rules:

• Activate server-side ad rules in the Publisher Settings of your ad plugin configuration.
• Set up ad rules for your inventory in Equativ Adserver UI.

When using server-side ad rules, after each ad call, our ad delivery server will either return the number of ads you defined in Equativ Adserver UI or a noad if you did not program any ads for the corresponding ad break.

Note that when Server-side ad rules are activated, ad calls for preroll and postroll breaks will automatically (and always) be triggered. You don't need to add client-side ad rules anymore for those breaks, they will be ignored.
However, for midroll breaks, the scheduling is still defined client-side until Equativ Instream Plugin supports VMAP. You can add ad rules for midrolls, the ad calls will be triggered based on your scheduling and the number of ad position will be determined by the ad rules you set-up server-side.

Sample

These ad rules are provided as a sample to help you 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
    }
]