# Módulo Kinescope para Drupal

> Módulo Kinescope para Drupal 10 e 11: instalação, token de API, métodos de incorporação do player, campo Kinescope, vídeos na biblioteca de mídia e em popup.

Fonte: https://docs-br.kinescope.com/integrations/integration-with-drupal/
Atualizado: 2026-10-19

Se o seu site roda em Drupal, você pode adicionar vídeos do Kinescope ao conteúdo com o módulo [Kinescope](https://www.drupal.org/project/kinescope). Você cola o link do vídeo em um campo, e o módulo exibe o player do Kinescope na página. O módulo é compatível com Drupal 10 e 11. A versão atual é a **1.3.1**.

O módulo é desenvolvido e mantido por parceiros do Kinescope. Para dúvidas e erros no módulo, use a [fila de issues do projeto no drupal.org](https://www.drupal.org/project/issues/kinescope).

> **Informação:**
>
> O módulo não faz upload de vídeos para o Kinescope. Envie o vídeo pelo [painel](https://app.kinescope.io), copie o link dele e cole no Drupal.

## Quando o módulo ajuda

- **Vídeo no conteúdo** — um player em um artigo, em uma página ou em um bloco, por meio de um campo próprio.
- **Vídeo na biblioteca de mídia do Drupal** — os vídeos do Kinescope ficam ao lado de imagens e documentos, e você pode reutilizá-los em qualquer conteúdo.
- **Dados do vídeo sem digitação manual** — com um token de API, o módulo busca o título, a descrição, a duração e o pôster.
- **Controle do player por JavaScript** — o módulo conecta a IFrame API, e você trata os eventos do player no código do tema.
- **Vídeo em popup** — a página mostra um pôster com link, e o player abre sobre a página.

Se algum desses cenários parece familiar, continue lendo.

## O que o módulo inclui

O projeto é dividido em quatro módulos. Ative só os que você precisa.

| Módulo | O que faz | Quando ativar |
| :--- | :--- | :--- |
| **Kinescope** | Configurações e requisições à API do Kinescope | Sempre |
| **Kinescope Player** | O tipo de campo Kinescope e a exibição do player | Sempre — sem ele, nenhum vídeo é exibido |
| **Kinescope Media** | Uma fonte Kinescope para a biblioteca de mídia do Drupal. Exige o módulo Media do core | Se você guarda os vídeos na biblioteca de mídia |
| **Kinescope Popup** | Abre o player em popup | Se você quer o player sobre a página |

## Como o módulo funciona (4 passos)

1. Você envia um vídeo ao Kinescope e copia o link dele.
2. Cola o link em um campo Kinescope ou adiciona o vídeo à biblioteca de mídia do Drupal.
3. Se houver um token de API, o módulo solicita ao Kinescope os dados do vídeo.
4. O Drupal exibe o player do Kinescope com o método de incorporação escolhido.

Agora vamos configurar.

## Instalação

1. Instale o módulo com o Composer:

   ```bash
   composer require drupal/kinescope
   ```

2. No painel administrativo do Drupal, abra **Extend** (`/admin/modules`).
3. Marque **Kinescope** e **Kinescope Player**. Se precisar, marque também **Kinescope Media** e **Kinescope Popup**.
4. Clique em **Install**.

> **Informação:**
>
> Os nomes de seções e botões do Drupal neste artigo seguem a interface em inglês. Caminhos como `/admin/...` não dependem do idioma da interface.

## Configurações do módulo

Todas as configurações ficam na página **Configuration → Media → Kinescope settings** (`/admin/config/media/kinescope`). Só papéis com a permissão **Administer Kinescope settings** podem abri-la.

### Modo sem token e modo com token

O módulo funciona sem token de API — esse é o modo padrão. O token acrescenta os dados do vídeo vindos da API do Kinescope.

| | Sem token | Com token |
| :--- | :--- | :--- |
| Player na página | Sim | Sim |
| Nome do vídeo na biblioteca de mídia | `Kinescope: ID do vídeo` | O título do vídeo no Kinescope |
| Miniatura na biblioteca de mídia | O pôster em `https://kinescope.io/ID/poster.webp` | O pôster dos dados do vídeo na API |
| Descrição, subtítulo, duração | Não | Sim |

Com token, o módulo solicita os dados do vídeo com `GET /v1/videos/{video_id}`.

Para conectar um token:

1. No [Kinescope](https://app.kinescope.io), abra **Configurações → Tokens de API** e crie um token. Saiba mais sobre tokens em [Regras Gerais da API](https://docs-br.kinescope.com/developer-guides/api-general-rules/).
2. No Drupal, cole o token no campo **API token** da página de configurações do Kinescope.
3. Clique em **Save configuration**.

Você também pode definir o token no `settings.php`:

```php
// Token da API do Kinescope para o módulo Kinescope
$settings['kinescope.api_token'] = 'SEU_TOKEN_DE_API';
```

O valor do `settings.php` tem prioridade: o campo **API token** do formulário fica bloqueado, e uma nota abaixo dele informa que o token está definido no arquivo.

> **Atenção:**
>
> Um token de API dá acesso ao seu workspace no Kinescope. Não publique o token nem o compartilhe com ninguém.

Para conferir se o Drupal enxerga o token, abra **Reports → Status report** (`/admin/reports/status`). A linha **Kinescope API token** mostra **Configured** ou o aviso **Not configured**.

### Método de incorporação do player

Na mesma página, na seção **Player**, escolha o **Embed method**. A configuração é global: vale para todos os campos Kinescope do site.

| Método | O que o módulo exibe |
| :--- | :--- |
| **Simple iframe embed** (padrão) | Um `<iframe>` comum, sem JavaScript — [incorporação simples](https://docs-br.kinescope.com/player-docs/embedding/simple-iframe-embed/) |
| **IFrame API (auto-connect)** | Um `<iframe>` com o parâmetro `enableIframeApi` e o script da IFrame API — [conexão automática à IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-auto-connect/) |
| **Web Components (experimental)** | O elemento `<kinescope-iframe-player>` — [web components](https://docs-br.kinescope.com/player-docs/embedding/web-components/) |

**IFrame API.** O módulo só conecta o player à IFrame API. O código que controla o player e trata os eventos dele você mesmo adiciona ao tema — veja os exemplos em [Conexão automática à IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api-auto-connect/).

**Web Components.** Nesse modo, o módulo passa ao elemento só o link do vídeo. Largura, altura e o valor de **Allow-list options** das configurações do campo não são aplicados.

> **Atenção:**
>
> Os web components do Kinescope são experimentais, então a API deles pode mudar.

## Vídeo em um campo do conteúdo

Este método não precisa da biblioteca de mídia: o vídeo fica direto no campo do conteúdo. Você pode adicionar um campo Kinescope a qualquer tipo de entidade — um nó, um bloco ou um parágrafo.

1. Abra **Structure → Content types** e escolha um tipo de conteúdo.
2. Clique em **Manage fields** e adicione um novo campo do tipo **Kinescope**.
3. Nas configurações do campo, decida quem define os parâmetros do player. A caixa **Allow editors to override player settings per video** controla isso:
   - **marcada** (padrão) — os editores definem os parâmetros de cada vídeo no formulário do conteúdo;
   - **desmarcada** — você define os parâmetros uma vez nas configurações do campo, e eles valem para todos os vídeos desse campo.
4. Salve as configurações do campo.

Parâmetros do player:

| Parâmetro | Padrão | Descrição |
| :--- | :--- | :--- |
| **Responsive** | Ativado | O player ocupa a largura do contêiner na proporção 16:9 |
| **Width**, **Height** | 640 × 480 | Tamanho do player em pixels. Ignorado quando **Responsive** está ativado |
| **Allow-list options** | `autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;` | O valor do atributo `allow` do `<iframe>` |

> **Atenção:**
>
> Não remova valores de **Allow-list options**: sem eles, a reprodução automática, a tela cheia, o Picture-in-Picture e o DRM podem parar de funcionar.

Agora adicione um vídeo ao conteúdo:

1. No Kinescope, copie o link do vídeo: botão **"Link"** acima do player → **"Copiar"**.
2. No formulário do conteúdo, cole o link no campo **Kinescope URL**.
3. Salve o conteúdo. O campo **Kinescope ID** é preenchido automaticamente.

O campo aceita links como estes:

- `https://kinescope.io/ID_DO_VIDEO`
- `https://kinescope.io/embed/ID_DO_VIDEO`

O link precisa começar com `https://` e não pode ter parâmetros depois de `?`. Caso contrário, o Drupal mostra o erro **The Kinescope URL is not valid**.

> **Atenção:**
>
> O módulo não suporta playlists — use links de vídeos individuais.

## Vídeo na biblioteca de mídia do Drupal

Para este método, ative o **Kinescope Media**. O módulo não cria um tipo de mídia sozinho — adicione um uma vez:

1. Abra **Structure → Media types → Add media type** (`/admin/structure/media/add`).
2. Digite um nome, por exemplo "Kinescope".
3. Em **Media source**, escolha **Kinescope** e salve o tipo.

O Drupal cria o campo **Kinescope URL** no tipo de mídia. O formulário não tem campo de nome: o módulo define o nome sozinho — a partir da API do Kinescope ou como `Kinescope: ID do vídeo`, se não houver token.

Você pode adicionar um vídeo à biblioteca de mídia de duas formas:

- **Pela seção Media.** Abra **Content → Media → Add media**, escolha o tipo Kinescope, cole o link e salve.
- **Pela janela da biblioteca de mídia.** Se o módulo **Media Library** do core estiver ativado, você adiciona o vídeo no próprio momento de escolher a mídia: na aba do tipo Kinescope, cole o link e clique em **Add**. Se não houver token, a janela mostra um aviso sobre isso.

Para exibir vídeos da biblioteca de mídia no conteúdo, adicione um campo **Media** ao tipo de conteúdo e permita nele o seu tipo de mídia Kinescope.

### Dados do vídeo nos campos de mídia

Com token, o módulo obtém dados do vídeo que você pode guardar em campos de mídia. Para isso, abra a seção **Field mapping** nas configurações do tipo de mídia e associe os dados aos campos.

| Dado no Drupal | O que contém |
| :--- | :--- |
| **Duration** | Duração do vídeo em segundos |
| **Description** | Descrição do vídeo |
| **Subtitles** | O subtítulo do vídeo — o campo `subtitle` da API, não um arquivo de legendas |
| **Thumbnail URI** | Caminho do pôster salvo |
| **Video URL** | Link do vídeo |

O módulo salva os pôsteres na pasta `kinescope_thumbs` do sistema de arquivos público do Drupal.

## Vídeo em popup

O módulo **Kinescope Popup** exibe um pôster com link no lugar do player. Ao clicar, o player abre em uma janela sobre a página.

1. Ative o **Kinescope Popup**.
2. Escolha o formato de exibição **Kinescope popup**:
   - para um campo Kinescope no conteúdo — em **Manage display** do tipo de conteúdo;
   - para vídeos da biblioteca de mídia — em **Manage display** do tipo de mídia Kinescope, no campo **Kinescope URL**. Não é preciso mudar o formato do campo **Media** no conteúdo.
3. Nas configurações do formato, defina o **Link text** — o texto ao lado do pôster. O padrão é **Play in popup**.

A janela fecha pelo botão de fechar, pela tecla **Esc** ou com um clique fora dela. Ao fechar, a reprodução para.

O link da janela é assinado com a chave do site e vale por uma hora. Só papéis com a permissão **View published content** podem abrir a janela.

## Atualização a partir das versões 1.1 e 1.2

Nas versões 1.1.x e 1.2.x, o Kinescope era um único módulo. A partir da 1.3, ele é dividido em quatro e funciona só com Drupal 10 e 11.

1. Atualize o módulo:

   ```bash
   composer require drupal/kinescope:^1.3
   ```

2. Execute as atualizações do banco de dados: `drush updb` ou a página `/update.php`. A atualização ativa o **Kinescope Player** e o **Kinescope Media** automaticamente.
3. Confira o método de incorporação na página de configurações do Kinescope.
4. Limpe o cache:

   ```bash
   drush cr
   ```

## Se algo não funcionar

**O player não aparece no site.** Verifique se a incorporação do vídeo está restrita por domínio. Se estiver, adicione o domínio do site aos permitidos — veja [Restrições de Acesso ao Vídeo](https://docs-br.kinescope.com/content-protection/access-restrictions/).

**O título e a descrição não são carregados.** Abra **Reports → Status report** e confira a linha **Kinescope API token**. Se o token estiver definido, veja o log do Drupal: com uma resposta `401` ou `403` da API, o módulo grava no canal `kinescope` um aviso pedindo para verificar o token. Enquanto o token não funcionar, o módulo exibe os vídeos sem os dados da API.

**O campo não aceita o link.** Confira se o link começa com `https://kinescope.io/` e não tem parâmetros depois de `?`.

## O que fazer a seguir?

Depois de configurar o módulo, recomendamos:

1. **[Restringir o acesso ao vídeo](https://docs-br.kinescope.com/content-protection/access-restrictions/)** — permita a reprodução só no domínio do seu site.
2. **[Configurar a proteção de conteúdo](https://docs-br.kinescope.com/content-protection/)** — ative a criptografia DRM e as marcas d'água.
3. **[Personalizar o player](https://docs-br.kinescope.com/video-player/player-customization/)** — ajuste a aparência do player à sua marca.
4. **[Conhecer a IFrame API](https://docs-br.kinescope.com/player-docs/embedding/iframe-api/)** — controle o player por JavaScript.

Dúvidas sobre o módulo? Pergunte aos desenvolvedores na [fila de issues do projeto no drupal.org](https://www.drupal.org/project/issues/kinescope).