API IFrame do YouTube: um guia prático

Pontos principais

• Carregue https://www.youtube.com/iframe_api uma só vez e crie os leitores em onYouTubeIframeAPIReady.

• Controle a reprodução com playVideo, pauseVideo, seekTo, mute e loadVideoById.

• Reaja a onStateChange e onError para registar reproduções e saltar vídeos com problemas.

• A API IFrame não precisa de chave; listar os vídeos de um canal ou de uma playlist exige a YouTube Data API, com chave e quotas.

Carregar a API e criar um leitor

<div id="player"></div>
<script src="https://www.youtube.com/iframe_api"></script>
<script>
  let player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player("player", {
      videoId: "VIDEO_ID",
      playerVars: { playsinline: 1, rel: 0 },
      events: { onReady: e => e.target.mute().playVideo() }
    });
  }
</script>

Métodos mais comuns

Eventos

onReady, onStateChange (a reproduzir, em pausa, terminado), onError. Use-os para medir visualizações ou iniciar o vídeo seguinte.

Quando não precisa da API

Para uma galeria, uma playlist ou um feed de canal em páginas de marketing, a API dá muito código para manter.

A via sem código

Mostre vídeos do YouTube num leitor com playlist, sem código de API.

Experimente o Elfsight Video Gallery

Como a API é carregada

A API IFrame é um único script. Quando termina de carregar, chama uma função global chamada onYouTubeIframeAPIReady — crie aí os seus leitores. Carregue o script uma só vez por página, mesmo que tenha vários leitores, e crie cada leitor no seu próprio elemento.

const players = {};
function onYouTubeIframeAPIReady() {
  document.querySelectorAll("[data-yt]").forEach((el) => {
    players[el.id] = new YT.Player(el.id, {
      videoId: el.dataset.yt,
      playerVars: { rel: 0, playsinline: 1 }
    });
  });
}

Estados do leitor

Ouça onStateChange e compare event.data com estas constantes.

Criar um botão de reprodução personalizado

<div id="player"></div>
<button id="play">Play</button>
<script>
  let player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player("player", { videoId: "VIDEO_ID", playerVars: { controls: 0 } });
  }
  document.getElementById("play").onclick = () => {
    const s = player.getPlayerState();
    s === YT.PlayerState.PLAYING ? player.pauseVideo() : player.playVideo();
  };
</script>

Ao ocultar os controlos do YouTube, passa a ser responsável por controlos acessíveis — suporte de teclado e etiquetas.

Registar reproduções e conclusões

events: {
  onStateChange: (e) => {
    const title = e.target.getVideoData().title;
    if (e.data === YT.PlayerState.PLAYING) gtag("event", "video_start", { video_title: title });
    if (e.data === YT.PlayerState.ENDED)   gtag("event", "video_complete", { video_title: title });
  }
}

Tratar erros

Ouça onError e passe ao vídeo seguinte da sua lista quando ocorrer um erro.

API IFrame vs. YouTube Data API

A API IFrame controla a reprodução de vídeos que já conhece. Para listar os envios de um canal ou os vídeos de uma playlist, precisa da YouTube Data API, que é separada — com chave de API, limites de quota diários e cache do seu lado. É a parte que a maioria das galerias personalizadas subestima.

A via sem código

Mostre um canal ou uma playlist como galeria sem a Data API, chaves ou quotas.

Experimente o Elfsight Video Gallery

Um exemplo completo: uma playlist de vídeos de produto

Um caso comum: um leitor, uma lista dos seus vídeos de produto ao lado e estatísticas de cada reprodução. Crie o leitor uma só vez, apresente a lista como botões com atributos data-id e chame loadVideoById ao clicar. Em ENDED, carregue o ID seguinte da lista para a playlist continuar. Envie eventos video_start e video_complete para as estatísticas com o título do vídeo. Tudo o resto — miniaturas, títulos, a ordem dos vídeos — vem dos seus próprios dados, que é exatamente a parte que a Data API ou um widget de galeria fornece.