# Call to Action (CTA)


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

This feature has `@experimental` status. It is stable enough to use, but API details may change. Follow the [player changelog](https://docs.kinescope.com/player-docs/changelog/).



A CTA is a call to action displayed over a video. Use it for subscriptions, links, timeline buttons, or lead forms. Configure CTAs in `playlist[].cta` when you [create a player](https://docs.kinescope.com/player-docs/embedding/iframe-api-create-player/#create-options). You can also use [`setPlaylistItemOptions`](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#setPlaylistItemOptions).

You can configure a simple CTA at the end of a video without code. Use a [player template](https://docs.kinescope.com/video-player/embedding/#configure-calls-to-action-cta-with-player-templates).

## Display types {#types}

The `type` field defaults to `overlay`:

| `type` | Behavior |
| :--- | :--- |
| `overlay` | Covers the player and pauses playback |
| `popup` | Shows a pop-up panel without pausing playback |
| `panel` | Shows a transparent panel without pausing playback |
| `banner` | Shows a banner with an image or link |
| `buttons` | Shows buttons over the frame. A click can move through the playlist or timeline |
| `leadgen` | Collects user data and sends it to your URL |

## Quick start: overlay

```js
function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/VIDEO_ID',
      playlist: [
        {
          cta: [
            {
              id: 'subscribe-cta',
              type: 'overlay', // Optional: this is the default value
              title: 'Did you enjoy the video?',
              description: 'Subscribe to the channel so you do not miss new releases.',
              skippable: true,
              button: { text: 'Subscribe' },
              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()
      })
    })
}
```

When a user clicks the CTA button, the [`CallAction`](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#Events.CallAction) event fires. Handle your action and close the screen with [`closeCTA()`](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/#closeCTA). Playback resumes after an overlay closes.

If you set `button.url`, the player can open the link. You still receive `CallAction`, which is useful for analytics.

## Common fields and trigger

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | Identifier included in `CallAction` |
| `type` | See [display types](#types) | Display mode. The default is `overlay` |
| `trigger.percentages` | `number[]` | Playback percentages, such as `[50, 100]` |
| `trigger.timePoints` | `number[]` | Time points in seconds, such as `[60, 600]` |
| `trigger.pause` | `boolean` | Shows the CTA when playback pauses |

Set at least one trigger: `percentages`, `timePoints`, or `pause`. You can combine them.

## overlay, popup, and panel

Common fields:

| Field | Type | Description |
| :--- | :--- | :--- |
| `title` | `string` | Title |
| `description` | `string` | Description |
| `skippable` | `boolean` | Lets the user close or skip the CTA |
| `button.text` | `string` | Button label |
| `button.style` | `CSSProperties` | Button styles |
| `button.url` | `string` | URL opened on click |

Additional fields:

| Field | Types | Description |
| :--- | :--- | :--- |
| `link` | `overlay` | Second link: `{ text, url, style? }` |
| `poster` | `overlay` | Poster or image on the CTA screen |
| `position` | `popup`, `panel` | `'top'` \| `'bottom'` |

Example of a `popup` displayed on pause:

```js
{
  id: 'pause-offer',
  type: 'popup',
  position: 'bottom',
  title: 'Continue later?',
  button: { text: 'Save progress', url: 'https://example.com/save' },
  skippable: true,
  trigger: { pause: true },
}
```

## banner

| Field | Type | Description |
| :--- | :--- | :--- |
| `title`, `description`, `skippable`, `button` | Same as `overlay` | Main fields |
| `url` | `string` | Banner link |
| `image` | `string` \| poster object | Image |
| `position` | `string` | `'top-left'` \| `'top-center'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-center'` \| `'bottom-right'` |
| `variant` | `'vertical' \| 'horizontal'` | Layout |
| `style` | `CSSProperties` | Container styles |

## buttons

This type shows buttons over the frame. Playback continues by default. Set `pause` on the item to pause it.

```js
{
  id: 'hotspots',
  type: 'buttons',
  trigger: { timePoints: [30] },
  list: [
    {
      id: 'go-chapter-2',
      title: 'Chapter 2',
      position: { x: 0.2, y: 0.5 }, // Relative to the frame, from 0 to 1
      goTo: { playlistItem: 0, time: 120 },
    },
  ],
}
```

| Field | Description |
| :--- | :--- |
| `list[].id` | Button ID |
| `list[].title` | Label |
| `list[].position` | `{ x, y }` relative to the frame size |
| `list[].goTo` | `number` for time in seconds, or `{ playlistItem, time? }` |
| `list[].style` | Button styles |
| `pause` | Pauses playback when the CTA appears |

## leadgen

This type collects user data. The player sends the fields to your `url` with a `POST` request.

| Field | Type | Description |
| :--- | :--- | :--- |
| `url` | `string` | Form submission endpoint |
| `fields` | `Array<'name' \| 'email' \| 'company'>` | Fields to show |
| `privacyPolicyUrl` | `string` | Privacy policy link |
| `lifetime` | `number` | How long this `id` counts as submitted. The default is 30 days |
| `skippable` | `boolean` | Lets the user close the form without submitting it |
| `trigger` | — | Same as other CTA types |

```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] },
}
```

## Next steps

- [Control the player](https://docs.kinescope.com/player-docs/embedding/iframe-api-control-player/) — use `closeCTA` and `CallAction`
- [Advertising](https://docs.kinescope.com/player-docs/advertising/) — configure VAST and IMA through the API
- [Playlists](https://docs.kinescope.com/player-docs/playlists/)
- [CTA in player templates](https://docs.kinescope.com/video-player/embedding/#configure-calls-to-action-cta-with-player-templates)