Ad Rules
Ad rules allow you to define the frequency and the size of ad breaks depending on your content duration. You can apply different advertising policies for short contents and long contents. You'll find all informations needed setup your ad rules in this page.
Overview
Ad rules allow you to define precise advertising policies depending on your content's duration.
Your ad rules can be created programmatically or directly from a JSON file hosted remotely.
Creating your own ad rules is not mandatory: if none are passed to the SVSAdManager instance on its creation a default SVSAdRules will be passed.
Structure
The structure of ad rules is based on 3 objects: SVSAdRules, SVSAdRule and SVSAdRuleData.
SVSAdRulesconsist of an array ofSVSAdRulethat you will pass to yourSVSAdManagerupon initialization.- An
SVSAdRuleis defined by a minimum duration, a maximum duration and a set ofSVSAdRuleData. SVSAdRuleDataare defined per ad break type (preroll, midroll, postroll) with a number of ad instances and specific timing datas for midrolls such as timecodes or percents.
You can check the API documentation for iOS or Android for more detailed description of the object model.
Integration
There are 2 ways to integrate your ad rules
- Programmatically, by initializing a
SVSAdRulesinstance from an array ofSVSAdRuleinstances. - or by loading a remote JSON file.
Initializing a SVSAdRules instance.
To instantiate a SVSAdRules instance, you need to instantiate SVSAdRuleData and SVSAdRule objects.
@property (nonatomic, strong) SVSAdRules *myAdRules;
- (void)instantiateAdRules {
// Instantiate 3 SVSAdRuleData for Preroll, Midroll and Postroll
SVSAdRuleData *prerollData = [SVSAdRuleData prerollDataWithInstances:1];
SVSAdRuleData *postrollData = [SVSAdRuleData postrollDataWithInstances:1];
SVSAdRuleData *midrollDataForOneHour = [SVSAdRuleData midrollDataWithInstances:2 percents:@[@(25),@(50),@(75)]];
SVSAdRuleData *midrollDataForLongerDuration = [SVSAdRuleData midrollDataWithInstances:2 interval:600];
// Instantiate a SVSAdRule with preroll and postroll SVSAdRuleData instances for a content duration between 0 and 600 seconds.
SVSAdRule *adRuleTenMinutes = [SVSAdRule adRuleWithData:@[prerollData, postrollData] durationMin:0 durationMax:600];
// Instantiate another SVSAdRule with preroll, postroll and midroll SVSADRuleData instances for a content duration between 600 and 3600 seconds.
SVSAdRule *adRuleOneHour = [SVSAdRule adRuleWithData:@[prerollData, midrollDataForOneHour, postrollData] durationMin:600 durationMax:3600];
// Instantiate another SVSAdRule with preroll, postroll and midroll SVSADRuleData instances for a content duration between 3600 seconds and more.
// Note that we use the constant kSVSAdRuleInfiniteDuration to define that the content is considered infinite.
SVSAdRule *adRuleLongerDuration = [SVSAdRule adRuleWithData:@[prerollData, midrollDataForLongerDuration, postrollData] durationMin:3600 durationMax:kSVSAdRuleInfiniteDuration];
// Instantiate the final SVSAdRules to be passed to the SVSAdManager
self.myAdRules = [SVSAdRules adRulesWithRules:@[adRuleTenMinutes, adRuleOneHour, adRuleLongerDuration]];
// Continue with your SVSAdManager initialization...
}
private SVSAdRule[] myAdRules;
public void instantiateAdRules() {
// Instantiate 3 SVSAdRuleData for Preroll, Midroll and Postroll
SVSAdRuleData prerollData = SVSAdRuleData.createPrerollAdRuleData(1, -1);
SVSAdRuleData postrollData = SVSAdRuleData.createPostrollAdRuleData(1, -1);
SVSAdRuleData midrollDataForOneHour = SVSAdRuleData.createMidrollAdRuleData(2, -1, new double[]{25, 50, 75});
SVSAdRuleData midrollDataForLongerDuration = SVSAdRuleData.createMidrollAdRuleData(2, -1, 600000, 0);
// Instantiate a SVSAdRule with preroll and postroll SVSAdRuleData instances for a content duration between 0 and 600 seconds.
SVSAdRule adRuleTenMinutes = new SVSAdRule(0, 600000, new SVSAdRuleData[]{prerollData, postrollData});
// Instantiate another SVSAdRule with preroll, postroll and midroll SVSADRuleData instances for a content duration between 600 and 3600 seconds.
SVSAdRule adRuleOneHour = new SVSAdRule(600000, 3600000, new SVSAdRuleData[]{prerollData, midrollDataForOneHour, postrollData});
// Instantiate another SVSAdRule with preroll, postroll and midroll SVSADRuleData instances for a content duration between 3600 seconds and more.
SVSAdRule adRuleLongerDuration = new SVSAdRule(3600000, -1, new SVSAdRuleData[]{prerollData, midrollDataForLongerDuration, postrollData});
// Instantiate the final SVSAdRules to be passed to the SVSAdManager
this.myAdRules = new SVSAdRule[]{adRuleTenMinutes, adRuleOneHour, adRuleLongerDuration};
// Continue with your SVSAdManager initialization
// …
}
Fetching your ad rules from a remote JSON file.
Hosting your ad rules in a JSON file on a remote server is a convenient way to modify your advertising policy without having to update your application.
@property (nonatomic, strong) SVSAdRules *myAdRules;
- (void)instantiateAdRules {
NSURL *myRemoteJSONURL = [NSURL URLWithString:@"https://www.domain.com/pathtojsonfile/adrules.json"];
[SVSAdRules adRulesFromURL:myRemoteJSONURL completionHandler:^(SVSAdRules *retrievedAdRules, NSError *error) {
if (error) {
NSLog(@"There was an error when retrieving JSON Ad Rules. %@", [error description]);
} else {
self.myAdRules = retrievedAdRules;
// Continue with your SVSAdManager initialization here.
}
}];
}
private static class AdRulesAsyncTask extends AsyncTask {
@Override
protected SVSAdRule[] doInBackground(String... urls) {
try {
// Retrieving ad rules from an url is a blocking task, you should not do it in the main thread
return SVSAdRulesUtils.parseAdRulesFromUrl(urls[0]).get();
} catch (Exception e) {
return null;
}
}
@Override
protected void onPostExecute(SVSAdRule[] adRules) {
if (adRules != null) {
// Continue with your SVSAdManager initialization here
// …
} else {
Log.e("TAG", "There was an error when retrieving JSON Ad Rules.");
}
}
}
// …
public void instantiateAdRules() {
// Launching the AsyncTask to retrieve the ad rules
new AdRulesAsyncTask().execute("https://www.domain.com/pathtojsonfile/adrules.json");
}
Here is an example on how you can define the same ad rules than on the previous section using a JSON file:
[
{
"duration_min": 0,
"duration_max": 600,
"data": {
"prerolls" : {
"instances" : 1
},
"postrolls" : {
"instances" : 1
}
}
},
{
"duration_min": 600,
"duration_max": 3600,
"data": {
"prerolls" : {
"instances" : 1
},
"midrolls" : {
"instances" : 2,
"percents" : [25,50,75]
},
"postrolls" : {
"instances" : 1
}
}
},
{
"duration_min": 3600,
"duration_max": -1,
"data": {
"prerolls" : {
"instances" : 1
},
"midrolls" : {
"instances" : 2,
"interval" : 600
},
"postrolls" : {
"instances" : 1
}
}
}
]
For both integrations we defined 3 different ad rules and the SVSAdManager will choose the correct one depending on the content's duration.
- For content between 0 (included) and 600 secondes (excluded), adRuleTenMinutes will be used and will display:
- one Preroll break of one ad
- one Postroll break of one ad
- For content between 600 and 3600 secondes, adRuleOneHour will be used and will display:
- one Preroll break of one ad
- Midroll breaks of two ads at 25%, 50% and 75% of the content's duration
- one Postroll break of one ad
- For content longer than 3600 secondes, adRuleLongerDuration will be used and will display:
- one Preroll break of one ad
- Midroll breaks of 2 ads every 600 seconds of content playback
- one Postroll break of one ad
Default ad rules
If you don't want to create your ad rules, the SDK will create its own SVSAdRules by default.
- For content with finite duration: the default ad rule will display one preroll ad and one postroll ad.
- For content with infinite duration (streamed/live): the default ad rule will display one preroll ad.
You can check the API documentation for iOS or Android for more detailed description.
Advanced Midrolls options
Midroll breaks can be fine tuned with several options for a better management of your advertisements.
Timing options
Midroll timing options can be defined in three different ways:
- Percents: an array of numbers between 0 and 100 to define relative times where the midroll breaks must be played. This will create cue points depending on a percentage of the content's duration.
- Timecodes: an array of strings with the format
HH:MM:SSto define precise times where the midroll breaks must be played. This will create cue points at specific time of your content. - Interval + offset: integers to define recurring midroll breaks. This will create cue points at precise times of your content: the offset is the time when the first midroll will be played and another midroll break will be scheduled every interval.
Note that 0 for offset will trigger a midroll immediately at the content begining, be careful with this value.
Minimum delay between ad breaks
For a better monetization, midroll breaks are always replayed when the user is seeking through your content. However this could be very annoying and for a better User Experience you can configure a minimum delay between ad breaks: no midroll breaks will be played until this delay is expired.
This option is set during the initialization of SVSAdRule objects, with the parameter minimumDelayBetweenAdBreaks.
For example:
minimumDelayBetweenAdBreaks between 30 and 60 seconds, the midroll will be skipped.minimumDelayBetweenAdBreaks lower than 30 seconds, the midroll will be displayed.
Live Content rules
When playing live/streamed content for which the duration is unknown, you need to set up a specific SVSAdRule.
In this SVSAdRule, preroll and postroll SVSAdRuleData are just as usual. However, midroll SVSAdRuleData are only supported when using offset and interval timing definition. Percents and timecodes timing will be rejected.
@property (nonatomic, strong) SVSAdRules *myAdRules;
- (void)instantiateAdRules {
// Instantiate 3 SVSAdRuleData for Preroll, Midroll and Postroll
SVSAdRuleData *prerollData = [SVSAdRuleData prerollDataWithInstances:1];
SVSAdRuleData *midrollData = [SVSAdRuleData midrollDataWithInstances:2 percents:@[@(25),@(50),@(75)]];
SVSAdRuleData *midrollDataForLiveContent = [SVSAdRuleData midrollDataWithInstances:2 interval:600 offset:300];
// Instantiate a SVSAdRule for content with any finite duration
SVSAdRule *adRule = [SVSAdRule adRuleWithData:@[prerollData, midrollData] durationMin:0 durationMax:-1];
// Instantiate another SVSAdRule for live content
SVSAdRule *adRuleForLiveContent = [SVSAdRule adRuleForLiveStreamContentWithData:@[prerollData, midrollDataForLiveContent] minimumDelayBetweenAdBreaks:300];
// Instantiate the final SVSAdRules to be passed to the SVSAdManager
self.myAdRules = [SVSAdRules adRulesWithRules:@[adRule, adRuleForLiveContent]];
// Continue with your SVSAdManager initialization...
}
private SVSAdRule[] myAdRules;
public void instantiateAdRules() {
// Instantiate 3 SVSAdRuleData for Preroll, Midroll and Postroll
SVSAdRuleData prerollData = SVSAdRuleData.createPrerollAdRuleData(1, -1);
SVSAdRuleData postrollData = SVSAdRuleData.createPostrollAdRuleData(1, -1);
SVSAdRuleData midrollDataForLiveContent = SVSAdRuleData.createMidrollAdRuleData(2, -1, 300000, 600000);
// Instantiate a SVSAdRule for content with any finite duration
SVSAdRule adRule = new SVSAdRule(0, -1, new SVSAdRuleData[]{prerollData, postrollData});
// Instantiate another SVSAdRule for live content
SVSAdRule adRuleForLiveContent = new SVSAdRule(-1, -1, new SVSAdRuleData[]{prerollData, midrollDataForLiveContent}, 300000);
// Instantiate the final SVSAdRules to be passed to the SVSAdManager
this.myAdRules = new SVSAdRule[]{adRule, adRuleForLiveContent};
// Continue with your SVSAdManager initialization
// …
}
We defined 2 different rules and the SVSAdManager will choose the correct one depending on the content duration:
- For content with a known duration:
- one preroll break of one ad
- midroll breaks of two ads at 25%, 50% and 75% of the content's duration
- For content with unknown duration (live / streamed):
- one preroll break of one ad when the stream starts
- midroll breaks after the first 300 secondes of content playback, then every 600 secondes
Server-side ad rules
Starting with Smart Instream SDK 7.7, you can use Server-side ad rules to manage your ad breaks.
In Smart 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
SVSAdPlayerConfigurationPublisherOptionsof yourSASAdManager. - Set up ad rules for your inventory in Smart 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 Smart 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 SVSAdRuleData anymore for those breaks, they will be ignored.
However, for midroll breaks, the scheduling is still defined client-side until Smart Instream SDK supports VMAP. You can add SASAdRuleData 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.