Define ad rules (Web Player)
Configure how often a viewer sees ads while watching your video content.
After adding ads to your content, you can define ad rules that control how often a viewer sees ads while watching your video content:
- If you are publishing playlists that consist of short-duration videos, like tutorials or product reviews, you can define
startOn
(the first playlist item allowing ad playback) andfrequency
(the regularity of ads within a playlist). - If you are publishing long-form content, like webinars or interviews, you can define
startOnSeek
(which determines if a returning visitor is served a pre-roll before resuming content playback) andtimeBetweenAds
(which sets the minimum time that must elapse between ads playback). - If you want to prevent ads from playing when the player is on an inactive tab, you can add
deferAds: {}
which prevents ad playback when the player's browser tab is inactive and plays the last deferred ad break when the player's browser tab is active again.
You can read the Ad rules reference to learn more about how each ad rule impacts a user's experience.
Be mindful of the following:
- When using a VAST (
vast
) ad client, you can define any of the fouradvertising.rules
properties.- When using an IMA (
googima
) or a FreeWheel (freewheel
) ad client, you can only definestartOn
andfrequency
.- When using Google's Dynamic Ad Insertion (
dai
) ad client, none of theadvertising.rules
properties are applicable.
Implementation
If you are using a cloud-hosted player, you can define the ad rules for an ad schedule in your JWP dashboard and associate the ad schedule with your cloud-hosted player. The ad schedule will play in every instance of the embedded player.
Use the following steps and code samples to define ad rules for an embedded player with an ad schedule:
- Add a rules object within the
advertising
object. - Configure the properties of the
rules
object for your use case.
You can build upon this basic implementation by setting up Player Bidding.
Examples
Example 1: Short-form content
The following example illustrates a short-form media item with a pre-roll. The first ad plays before the first playlist item (startOn: 1
). Then, subsequent pre-rolls appear for every third playlist item (frequency: 3
), starting with the fourth playlist item.
jwplayer("myElement").setup({
playlist: "https://cdn.jwplayer.com/v2/playlists/{playlist_id}",
advertising: {
client: "vast",
schedule: [
{
offset: "pre",
tag: "https://www.domain.com/adtag.xml"
}
],
rules: {
startOn: 1,
frequency: 3
}
}
});
Example 2: Long-form content
The following example illustrates a long-form media item with multiple ad breaks. The startOnSeek
and timeBetweenAds
(set to 300 seconds) ad rules have been defined.
jwplayer("myElement").setup({
playlist: "https://cdn.jwplayer.com/v2/media/{media_id}",
advertising: {
client: "vast",
schedule: [
{
offset: "pre",
tag: "https://www.domain.com/adtag.xml"
},
{
offset: 10,
tag: "https://www.domain.com/adtag-mid-roll1.xml"
},
{
offset: "00:00:15:000",
tag: "https://www.domain.com/adtag-mid-roll2.xml"
},
{
offset: "25%",
tag: "https://www.domain.com/adtag-midroll3.xml"
},
{
offset: "post",
tag: "https://www.domain.com/adtag-midroll3.xml"
}
],
rules: {
startOnSeek: "pre",
timeBetweenAds: 300
}
}
});
Example 3: Long-form content with deferred ad playback
The following example illustrates a long-form media item with multiple ad breaks. The deferAds{}
and timeBetweenAds
(set to 300 seconds) ad rules have been defined.
jwplayer("myElement").setup({
playlist: "https://cdn.jwplayer.com/v2/media/{media_id}",
advertising: {
client: "vast",
schedule: [
{
offset: "pre",
tag: "https://www.domain.com/adtag.xml"
},
{
offset: 300,
tag: "https://www.domain.com/adtag-mid-roll1.xml"
},
{
offset: "00:10:15:000",
tag: "https://www.domain.com/adtag-mid-roll2.xml"
},
{
offset: "25%",
tag: "https://www.domain.com/adtag-midroll3.xml"
},
{
offset: "50%",
tag: "https://www.domain.com/adtag-midroll4.xml"
},
{
offset: "75%",
tag: "https://www.domain.com/adtag-midroll5.xml"
},
{
offset: "post",
tag: "https://www.domain.com/adtag-midroll3.xml"
}
],
rules: {
timeBetweenAds: 300,
deferAds: {}
}
}
});
For this example, assume the video is 60 minutes and a viewer takes the following actions:
- Starts this video from the beginning
- Opens a new tab when the video time is
00:10:00:000
- Returns to the video when the video time is
00:42:10:000
Based on the code example, the viewer would view the following ads:
- The pre-roll (
offset: "pre"
) and first mid-roll (offset: 300
) ads before opening a new tab - The fourth mid-roll ad (
offset: "50%"
) when she returns to the player's browser tab at00:42:10:000
- The post-roll ad
The second and third mid-roll ads would not be played due to the deferAds{}
rule. The last mid-roll would not be played due to timeBetweenAds
.
Updated about 2 months ago