# 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](https://docs.kinescope.com/video-player/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`

```html
<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()`](https://docs.kinescope.com/player-docs/embedding/iframe-api-create-player/#create) or with [`setPlaylistItemOptions`](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#setPlaylistItemOptions).

### Pre-roll from a tag URL

```js
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`:

```js
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](https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side) request object (`adsRequest`) |
| `yaOptions` | `@experimental` | [Yandex Video Ads SDK](https://yandex.ru/dev/video-sdk/doc/ru/sdk-html5/AdConfig-interface) settings |

Use only one of these fields in each ad item.

Example with complete tag text:

```js
ad: {
  adTag: `<?xml version="1.0"?><VAST version="3.0">…</VAST>`,
}
```

## Ad break event

```js
player.on(player.Events.AdBreakStateChanged, (event) => {
  if (event.data.active) {
    // An ad is playing
  } else {
    // The ad break has ended
  }
})
```

The [`AdBreakStateChanged`](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#Events.AdBreakStateChanged) event has `@experimental` status.

## Next steps

- [Control the player](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/) — configure `playlist[].ad` and handle events
- [DRM encryption](https://docs.kinescope.com/content-protection/drm-encryption/) — review content protection limitations
- [Advertising in player templates](https://docs.kinescope.com/video-player/advertising/) — configure ads without the API
- [Simple iframe embedding](https://docs.kinescope.com/player-docs/embedding/simple-iframe-embed/) — explore other URL parameters