# Call To Action (CTA)


> **Информация:**

Функция в статусе `@experimental`: достаточно стабильна для использования, но детали API могут измениться. Следите за [изменениями плеера](https://docs.kinescope.ru/dokumentaciya-pleera/izmeneniya/).



CTA — призыв к действию поверх видео: подписка, переход по ссылке, кнопки на таймлайне или форма сбора контактов. Задаётся в `playlist[].cta` при [создании плеера](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-sozdanie-pleera/#create-options) или через [`setPlaylistItemOptions`](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/#setPlaylistItemOptions).

Простой CTA в конце ролика можно настроить без кода — в [шаблоне плеера](https://docs.kinescope.ru/videopleer-nastrojka-i-vstraivanie/vstraivanie/#настройка-призывов-к-действию-cta-через-шаблоны-плеера).

## Типы показа {#types}

Поле `type` (по умолчанию `overlay`):

| `type` | Поведение |
| :--- | :--- |
| `overlay` | Перекрывает плеер, останавливает воспроизведение |
| `popup` | Всплывающая панель, воспроизведение не останавливает |
| `panel` | Прозрачная панель, воспроизведение не останавливает |
| `banner` | Баннер с картинкой/ссылкой |
| `buttons` | Набор кнопок на кадре (клик → переход по плейлисту/времени) |
| `leadgen` | Диалог сбора данных пользователя и отправки на ваш URL |

## Быстрый старт: overlay

```js
function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/VIDEO_ID',
      playlist: [
        {
          cta: [
            {
              id: 'subscribe-cta',
              type: 'overlay', // можно не указывать — это значение по умолчанию
              title: 'Понравилось видео?',
              description: 'Подпишитесь на канал, чтобы не пропустить новые выпуски.',
              skippable: true,
              button: { text: 'Подписаться' },
              trigger: { percentages: [50] },
            },
          ],
        },
      ],
    })
    .then((player) => {
      player.on(player.Events.CallAction, (event) => {
        // event.data.id === 'subscribe-cta'
        window.open('https://example.com/subscribe', '_blank')
        player.closeCTA()
      })
    })
}
```

Когда пользователь нажимает кнопку CTA, срабатывает [`CallAction`](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/#Events.CallAction). В обработчике выполните своё действие и закройте экран через [`closeCTA()`](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/#closeCTA) — для overlay после этого воспроизведение продолжится.

Если у кнопки задан `button.url`, плеер может открыть ссылку сам; `CallAction` всё равно приходит — удобно для аналитики.

## Общие поля и trigger

| Поле | Тип | Описание |
| :--- | :--- | :--- |
| `id` | `string` | Идентификатор; приходит в `CallAction` |
| `type` | см. [типы](#types) | Вариант показа; по умолчанию `overlay` |
| `trigger.percentages` | `number[]` | Процент воспроизведения, например `[50, 100]` |
| `trigger.timePoints` | `number[]` | Точки времени в секундах, например `[60, 600]` |
| `trigger.pause` | `boolean` | Показать CTA при постановке на паузу |

Укажите хотя бы один способ срабатывания: `percentages`, `timePoints` или `pause` (можно комбинировать).

## overlay, popup, panel

Общие поля:

| Поле | Тип | Описание |
| :--- | :--- | :--- |
| `title` | `string` | Заголовок |
| `description` | `string` | Описание |
| `skippable` | `boolean` | Можно закрыть / пропустить |
| `button.text` | `string` | Текст кнопки |
| `button.style` | `CSSProperties` | Стили кнопки |
| `button.url` | `string` | URL по нажатию |

Дополнительно:

| Поле | Типы | Описание |
| :--- | :--- | :--- |
| `link` | `overlay` | Вторая ссылка: `{ text, url, style? }` |
| `poster` | `overlay` | Постер / картинка на экране CTA |
| `position` | `popup`, `panel` | `'top'` \| `'bottom'` |

Пример `popup` на паузе:

```js
{
  id: 'pause-offer',
  type: 'popup',
  position: 'bottom',
  title: 'Продолжить позже?',
  button: { text: 'Сохранить прогресс', url: 'https://example.com/save' },
  skippable: true,
  trigger: { pause: true },
}
```

## banner

| Поле | Тип | Описание |
| :--- | :--- | :--- |
| `title`, `description`, `skippable`, `button` | как у overlay | Основные поля |
| `url` | `string` | Ссылка баннера |
| `image` | `string` \| объект постера | Картинка |
| `position` | `string` | `'top-left'` \| `'top-center'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-center'` \| `'bottom-right'` |
| `variant` | `'vertical' \| 'horizontal'` | Раскладка |
| `style` | `CSSProperties` | Стили контейнера |

## buttons

Набор кнопок на кадре. Воспроизведение по умолчанию не останавливается (`pause` на элементе — опционально).

```js
{
  id: 'hotspots',
  type: 'buttons',
  trigger: { timePoints: [30] },
  list: [
    {
      id: 'go-chapter-2',
      title: 'Глава 2',
      position: { x: 0.2, y: 0.5 }, // относительно кадра, 0…1
      goTo: { playlistItem: 0, time: 120 },
    },
  ],
}
```

| Поле | Описание |
| :--- | :--- |
| `list[].id` | ID кнопки |
| `list[].title` | Текст |
| `list[].position` | `{ x, y }` относительно размера кадра |
| `list[].goTo` | `number` (время, сек) или `{ playlistItem, time? }` |
| `list[].style` | Стили кнопки |
| `pause` | Поставить на паузу при показе |

## leadgen

Диалог сбора данных. Поля отправляются `POST` на ваш `url`.

| Поле | Тип | Описание |
| :--- | :--- | :--- |
| `url` | `string` | Endpoint для отправки формы |
| `fields` | `Array<'name' \| 'email' \| 'company'>` | Какие поля показать |
| `privacyPolicyUrl` | `string` | Ссылка на политику конфиденциальности |
| `lifetime` | `number` | Сколько считать форму уже отправленной для этого `id` (по умолчанию 30 дней) |
| `skippable` | `boolean` | Можно закрыть без отправки |
| `trigger` | — | Как у остальных типов |

```js
{
  id: 'lead-end',
  type: 'leadgen',
  url: 'https://example.com/api/leads',
  fields: ['name', 'email'],
  privacyPolicyUrl: 'https://example.com/privacy',
  skippable: true,
  trigger: { percentages: [100] },
}
```

## Что дальше?

- [Управление плеером](https://docs.kinescope.ru/dokumentaciya-pleera/vstraivanie/iframe-api-upravlenie-pleerom/) — `closeCTA`, `CallAction`
- [Реклама](https://docs.kinescope.ru/dokumentaciya-pleera/reklama/) — VAST/IMA через API
- [Плейлисты](https://docs.kinescope.ru/dokumentaciya-pleera/pleylisty/)
- [CTA в шаблонах](https://docs.kinescope.ru/videopleer-nastrojka-i-vstraivanie/vstraivanie/#настройка-призывов-к-действию-cta-через-шаблоны-плеера)