Módulo Kinescope para Drupal

Se o seu site roda em Drupal, você pode adicionar vídeos do Kinescope ao conteúdo com o módulo 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.

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.

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:

   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.

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.

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

Para conectar um token:

1. No Kinescope, abra Configurações → Tokens de API e crie um token. Saiba mais sobre tokens em Regras Gerais da API.
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:

// 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.

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.

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.

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.

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:

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.

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.

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:

   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:

   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.

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 — permita a reprodução só no domínio do seu site.
2. Configurar a proteção de conteúdo — ative a criptografia DRM e as marcas d’água.
3. Personalizar o player — ajuste a aparência do player à sua marca.
4. Conhecer a 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.