Advertising
The player can show video ads from a VAST or VPAID tag, or through Google IMA. Configure ads with a URL parameter or the IFrame API.
For a basic setup without the API, see Advertising in the product documentation. This page covers programmatic setup.
Ads may not work with DRM-protected videos. Ad blockers and browser autoplay policies can also prevent ads from playing.
Simple embedding with adtagurl
<iframe
src="https://kinescope.io/embed/VIDEO_ID?adtagurl=https%3A%2F%2Fexample.com%2Fvast.xml"
allow="autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;"
style="border: none;"
></iframe>
The adtagurl value must be URL-encoded. This parameter has @experimental status.
IFrame API: playlist[].ad
Set this field in create()
or with setPlaylistItemOptions
.
Pre-roll from a tag URL
playerFactory.create('player', {
url: 'https://kinescope.io/VIDEO_ID',
playlist: [
{
ad: {
adTagUrl: 'https://example.com/vast.xml',
},
},
],
})
You can pass an array of URLs: adTagUrl: ['https://…/a.xml', 'https://…/b.xml'].
Mid-roll and multiple points
To set ad points, pass an array of items with trigger:
playlist: [
{
ad: [
{
id: 'preroll',
adTagUrl: 'https://example.com/preroll.xml',
trigger: { percentages: [0] },
},
{
id: 'midroll',
adTagUrl: 'https://example.com/midroll.xml',
trigger: { timePoints: [60, 180] },
},
{
id: 'every-10-min',
adTagUrl: 'https://example.com/recurring.xml',
trigger: { interval: 600 }, // Every 10 minutes
},
],
},
]
trigger field | Description |
|---|---|
percentages | Percentage of the current playback time, such as [0, 50] |
timePoints | Time in seconds, such as [60, 600] |
interval | Repeats every N seconds, such as 600 |
Set one trigger type in each ad item.
Ad source options
| Field | Status | Description |
|---|---|---|
adTagUrl | Public | VAST or VPAID tag URL, or an array of URLs |
adTag | @experimental | Complete tag text, or an array of tags |
adsRequest | @experimental | Google IMA
request object (adsRequest) |
yaOptions | @experimental | Yandex Video Ads SDK settings |
Use only one of these fields in each ad item.
Example with complete tag text:
ad: {
adTag: `<?xml version="1.0"?><VAST version="3.0">…</VAST>`,
}
Ad break event
player.on(player.Events.AdBreakStateChanged, (event) => {
if (event.data.active) {
// An ad is playing
} else {
// The ad break has ended
}
})
The AdBreakStateChanged
event has @experimental status.
Next steps
- Control the player
— configure
playlist[].adand handle events - DRM encryption — review content protection limitations
- Advertising in player templates — configure ads without the API
- Simple iframe embedding — explore other URL parameters