Widgets Incorporáveis
Ao lado do player incorporado você pode colocar dois widgets — a lista da playlist e a lista de capítulos do vídeo atual. Antes essa lista existia apenas na página pública do Kinescope; agora ela pode ser incorporada no seu site como um bloco separado.
| Widget | Para que serve | Onde está disponível |
|---|---|---|
| Playlist | Lista de vídeos com miniatura, título e duração. Um clique troca o vídeo no player | Playlist com dois ou mais vídeos |
| Capítulos | Lista de capítulos com marcações de tempo. Um clique pula para o capítulo | Vídeo individual que tenha capítulos |
Os widgets não se sobrepõem: a playlist oferece apenas o widget de playlist, e o vídeo apenas o widget de capítulos.
Onde obter o código
- Abra as configurações do vídeo ou da playlist no painel de controle e clique em Incorporar.
- Vá para a aba Capítulos (no vídeo) ou Playlist (na playlist).
- Escolha o tema do widget:
Automático,ClaroouEscuro. - Escolha o tipo de código: responsivo — o widget ocupa o bloco em que é inserido, ou tamanho fixo — com largura e altura em pixels (400 × 600 por padrão).
- Copie o script — ele entra na página uma única vez, independentemente da quantidade de widgets.
- Clique em Copiar código de incorporação — o bloco do widget vai para a área de transferência.
Na playlist o mesmo painel abre na aba Playlist:
As abas não aparecem sempre:
- Capítulos — apenas se os capítulos estiverem ativados no vídeo. Como adicioná-los — no artigo Trabalhando com arquivos: legendas, capítulos e mais.
- Playlist — apenas se a playlist tiver mais de um vídeo.
Código de incorporação
O widget é composto por duas partes: o script carregador e o bloco container.
O script — uma vez por página, normalmente antes do </body> de fechamento:
<script src="https://widgets.kinescope.io/latest/loader.js"></script>
O container — no lugar onde o widget deve aparecer:
<!-- Widget de playlist -->
<div id="kinescope-widget-playlist" data-id="PLAYLIST_ID"></div>
<!-- Widget de capítulos -->
<div id="kinescope-widget-chapters" data-id="VIDEO_ID"></div>
PLAYLIST_ID e VIDEO_ID são os identificadores da playlist e do vídeo no painel de controle. Não é preciso preenchê-los manualmente: o código copiado já os contém.
O carregador insere no container um iframe com o widget e o conecta ao player da página.
Tamanho do widget
O widget ocupa o bloco em que é inserido: a largura vem da largura do bloco, e a altura, da altura dele. Por isso, defina a altura na sua marcação — pelo CSS do bloco ou pelo atributo data-height.
Para que a lista fique exatamente da altura do player, coloque o player e o widget na mesma linha da grade e informe data-height="100%" ao widget.
Exemplo: player e widget de capítulos lado a lado
<!DOCTYPE html>
<html>
<head>
<style>
.layout { display: grid; gap: 16px; align-items: stretch; }
@media (min-width: 900px) {
.layout { grid-template-columns: minmax(0, 1fr) 320px; }
}
.player { position: relative; width: 100%; aspect-ratio: 16 / 9; }
.player iframe { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; }
.widget { min-height: 280px; }
</style>
</head>
<body>
<h1>Aula 1</h1>
<div class="layout">
<!-- Player -->
<div class="player">
<iframe
src="https://kinescope.io/embed/VIDEO_ID"
allow="autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;"
frameborder="0"
allowfullscreen
></iframe>
</div>
<!-- Widget de capítulos -->
<div id="kinescope-widget-chapters" class="widget" data-id="VIDEO_ID" data-height="100%"></div>
</div>
<script src="https://widgets.kinescope.io/latest/loader.js"></script>
</body>
</html>
Veja como o widget de capítulos fica na página, ao lado do player:
O widget de playlist é incorporado da mesma forma — com o player da playlist (https://kinescope.io/embed/pl/PLAYLIST_ID) e o container kinescope-widget-playlist. Mais sobre playlists no player — no artigo Playlists.
Parâmetros
Todos os parâmetros são definidos como atributos do container. No painel de controle eles são preenchidos automaticamente, conforme o tema e o tipo de código escolhidos.
| Atributo | Valores | Descrição |
|---|---|---|
data-id | ID do vídeo ou da playlist | Obrigatório. Define o que o widget mostra |
data-theme | light, dark | Tema do widget. Para o tema Automático o atributo não é adicionado — o widget segue o tema do navegador do espectador |
data-width | 100%, tamanho em px | Largura do widget. Sem o atributo — a largura do bloco container |
data-height | 100%, tamanho em px | Altura do widget. Sem o atributo — a altura do bloco container |
O tema do widget não está vinculado ao tema do player — é uma configuração independente. A interface do widget (títulos, dicas) aparece no idioma do navegador do espectador.
Sincronização com o player
O widget encontra o player Kinescope na página por conta própria — nenhum código extra é necessário. Três cenários funcionam: dois iframes lado a lado, um player criado pela IFrame API com o widget, e o player de incorporação comum com o widget.
O que acontece em seguida:
- trocar o vídeo no player destaca a linha ativa no widget de playlist;
- a reprodução destaca o capítulo atual no widget de capítulos;
- clicar em um vídeo troca o player, e clicar em um capítulo avança para o início dele;
- se o player for recriado, o widget se reconecta automaticamente.
Se o conteúdo mudar — você adicionou um vídeo à playlist ou um capítulo ao vídeo —, o widget no site acompanha a mudança sozinho. Não é preciso incorporar o código de novo.
No mobile
Em telas estreitas o widget fica recolhido: a lista abre com um toque e desliza de baixo para cima sobre a página. O player permanece no lugar. Não é necessário nenhum código separado para a versão mobile.
Estados vazios
| O que o espectador vê | Quando |
|---|---|
| Não há capítulos | Os capítulos do vídeo foram excluídos ou ocultados depois que o widget foi incorporado |
| Sem dados | Restou apenas um vídeo na playlist |
| Esta incorporação não está disponível | O vídeo ou a playlist foi excluído ou não está disponível para incorporação |
O widget continua na página e não quebra o layout.
Limitações
- O widget não funciona sem um player Kinescope na mesma página.
- Não é possível editar a playlist ou os capítulos pelo widget — isso é feito no painel de controle.
- Além do tema e do tamanho, a aparência não é configurável: fontes, cores e miniaturas não podem ser alteradas.
- Dentro do widget a lista tem rolagem: se o bloco for mais baixo que a lista, apenas parte dos vídeos ou capítulos fica visível — a linha ativa aparece destacada.
- A playlist não tem widget de capítulos, e o vídeo individual não tem widget de playlist.
O que vem depois?
- Incorporação — código de incorporação do player, tamanhos e parâmetros
- Playlists — como montar uma playlist no catálogo
- Trabalhando com arquivos: legendas, capítulos e mais — como adicionar capítulos a um vídeo
- Personalização do player — a aparência do player de acordo com a sua marca
Ainda tem dúvidas? Escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudá-lo!