# Chamada para ação (CTA)


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

Este recurso tem status `@experimental`. Ele é estável o suficiente para uso, mas os detalhes da API podem mudar. Acompanhe o [histórico de alterações do player](https://docs-br.kinescope.com/player-docs/changelog/).



Uma CTA é uma chamada para ação exibida sobre o vídeo. Use-a para assinaturas, links, botões na linha do tempo ou formulários de captação de leads. Configure as CTAs em `playlist[].cta` ao [criar um player](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-create-player/#create-options). Você também pode usar [`setPlaylistItemOptions`](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/#setPlaylistItemOptions).

Você pode configurar uma CTA simples no final do vídeo sem escrever código. Use um [modelo de player](https://docs-br.kinescope.com/video-player/embedding/#configure-calls-to-action-cta-with-player-templates).

## Tipos de exibição {#tipos}

O valor padrão do campo `type` é `overlay`:

| `type` | Comportamento |
| :--- | :--- |
| `overlay` | Cobre o player e pausa a reprodução |
| `popup` | Exibe um painel pop-up sem pausar a reprodução |
| `panel` | Exibe um painel transparente sem pausar a reprodução |
| `banner` | Exibe um banner com uma imagem ou um link |
| `buttons` | Exibe botões sobre o quadro. Um clique pode navegar pela playlist ou pela linha do tempo |
| `leadgen` | Coleta dados do usuário e os envia para sua URL |

## Início rápido: overlay

```js
function onKinescopeIframeAPIReady(playerFactory) {
  playerFactory
    .create('player', {
      url: 'https://kinescope.io/VIDEO_ID',
      playlist: [
        {
          cta: [
            {
              id: 'subscribe-cta',
              type: 'overlay', // Opcional: este é o valor padrão
              title: 'Você gostou do vídeo?',
              description: 'Assine o canal para não perder os próximos lançamentos.',
              skippable: true,
              button: { text: 'Assinar' },
              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()
      })
    })
}
```

Quando o usuário clica no botão da CTA, o evento [`CallAction`](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/#Events.CallAction) é disparado. Execute sua ação e feche a tela com [`closeCTA()`](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/#closeCTA). A reprodução continua depois que a sobreposição é fechada.

Se você definir `button.url`, o player poderá abrir o link. O evento `CallAction` ainda será enviado, o que é útil para análises.

## Campos comuns e acionamento

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `id` | `string` | Identificador incluído em `CallAction` |
| `type` | Consulte os [tipos de exibição](#tipos) | Modo de exibição. O padrão é `overlay` |
| `trigger.percentages` | `number[]` | Percentuais de reprodução, como `[50, 100]` |
| `trigger.timePoints` | `number[]` | Pontos no tempo em segundos, como `[60, 600]` |
| `trigger.pause` | `boolean` | Exibe a CTA quando a reprodução é pausada |

Defina pelo menos um acionador: `percentages`, `timePoints` ou `pause`. Você pode combiná-los.

## overlay, popup e panel

Campos comuns:

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `title` | `string` | Título |
| `description` | `string` | Descrição |
| `skippable` | `boolean` | Permite que o usuário feche ou pule a CTA |
| `button.text` | `string` | Texto do botão |
| `button.style` | `CSSProperties` | Estilos do botão |
| `button.url` | `string` | URL aberta ao clicar |

Campos adicionais:

| Campo | Tipos | Descrição |
| :--- | :--- | :--- |
| `link` | `overlay` | Segundo link: `{ text, url, style? }` |
| `poster` | `overlay` | Pôster ou imagem na tela da CTA |
| `position` | `popup`, `panel` | `'top'` \| `'bottom'` |

Exemplo de `popup` exibido ao pausar:

```js
{
  id: 'pause-offer',
  type: 'popup',
  position: 'bottom',
  title: 'Continuar depois?',
  button: { text: 'Salvar progresso', url: 'https://example.com/save' },
  skippable: true,
  trigger: { pause: true },
}
```

## banner

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `title`, `description`, `skippable`, `button` | Igual a `overlay` | Campos principais |
| `url` | `string` | Link do banner |
| `image` | `string` \| objeto de pôster | Imagem |
| `position` | `string` | `'top-left'` \| `'top-center'` \| `'top-right'` \| `'bottom-left'` \| `'bottom-center'` \| `'bottom-right'` |
| `variant` | `'vertical' \| 'horizontal'` | Layout |
| `style` | `CSSProperties` | Estilos do contêiner |

## buttons

Este tipo exibe botões sobre o quadro. Por padrão, a reprodução continua. Defina `pause` no item para pausá-la.

```js
{
  id: 'hotspots',
  type: 'buttons',
  trigger: { timePoints: [30] },
  list: [
    {
      id: 'go-chapter-2',
      title: 'Capítulo 2',
      position: { x: 0.2, y: 0.5 }, // Em relação ao quadro, de 0 a 1
      goTo: { playlistItem: 0, time: 120 },
    },
  ],
}
```

| Campo | Descrição |
| :--- | :--- |
| `list[].id` | ID do botão |
| `list[].title` | Texto |
| `list[].position` | `{ x, y }` em relação ao tamanho do quadro |
| `list[].goTo` | `number` para o tempo em segundos ou `{ playlistItem, time? }` |
| `list[].style` | Estilos do botão |
| `pause` | Pausa a reprodução quando a CTA aparece |

## leadgen

Este tipo coleta dados do usuário. O player envia os campos para sua `url` por meio de uma solicitação `POST`.

| Campo | Tipo | Descrição |
| :--- | :--- | :--- |
| `url` | `string` | Endpoint de envio do formulário |
| `fields` | `Array<'name' \| 'email' \| 'company'>` | Campos que serão exibidos |
| `privacyPolicyUrl` | `string` | Link para a política de privacidade |
| `lifetime` | `number` | Período durante o qual este `id` é considerado enviado. O padrão é 30 dias |
| `skippable` | `boolean` | Permite que o usuário feche o formulário sem enviá-lo |
| `trigger` | — | Igual aos outros tipos de CTA |

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

## Próximos passos

- [Controlar o player](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-control-player/) — use `closeCTA` e `CallAction`
- [Publicidade](https://docs-br.kinescope.com/player-docs/advertising/) — configure VAST e IMA pela API
- [Playlists](https://docs-br.kinescope.com/player-docs/playlists/)
- [CTA em modelos de player](https://docs-br.kinescope.com/video-player/embedding/#configure-calls-to-action-cta-with-player-templates)