YouTube IFrame API: ein praktischer Leitfaden

Das Wichtigste in Kürze

• Laden Sie https://www.youtube.com/iframe_api einmal und erstellen Sie die Player in onYouTubeIframeAPIReady.

• Steuern Sie die Wiedergabe mit playVideo, pauseVideo, seekTo, mute und loadVideoById.

• Reagieren Sie auf onStateChange und onError, um Wiedergaben zu erfassen und fehlerhafte Videos zu überspringen.

• Die IFrame API braucht keinen Schlüssel; für die Liste der Videos eines Kanals oder einer Playlist benötigen Sie die YouTube Data API mit Schlüssel und Kontingenten.

API laden und einen Player erstellen

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

Gängige Methoden

Ereignisse

onReady, onStateChange (läuft, pausiert, beendet), onError. Damit erfassen Sie Aufrufe oder starten das nächste Video.

Wann Sie die API nicht brauchen

Für eine Galerie, Playlist oder einen Kanal-Feed auf Marketingseiten ist die API ein Haufen Code, den Sie pflegen müssen.

Der Weg ohne Code

Zeigen Sie YouTube-Videos in einem Player mit Playlist – ohne API-Code.

Elfsight Video Gallery ausprobieren

So lädt die API

Die IFrame API besteht aus einem einzigen Skript. Sobald es geladen ist, ruft es eine globale Funktion namens onYouTubeIframeAPIReady auf – erstellen Sie Ihre Player dort. Laden Sie das Skript nur einmal pro Seite, auch wenn Sie mehrere Player haben, und erstellen Sie jeden Player auf einem eigenen Element.

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 }
    });
  });
}

Player-Status

Lauschen Sie auf onStateChange und vergleichen Sie event.data mit diesen Konstanten.

Eigenen Play-Button bauen

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

Wenn Sie die Steuerelemente von YouTube ausblenden, sind Sie selbst für barrierefreie Bedienelemente verantwortlich – Tastaturbedienung und Beschriftungen.

Wiedergaben und Abschlüsse erfassen

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 });
  }
}

Fehler behandeln

Lauschen Sie auf onError und springen Sie bei einem Fehler zum nächsten Video Ihrer Liste.

IFrame API vs. YouTube Data API

Die IFrame API steuert die Wiedergabe von Videos, die Sie bereits kennen. Um die Uploads eines Kanals oder die Videos einer Playlist aufzulisten, brauchen Sie die separate YouTube Data API – mit API-Schlüssel, täglichen Kontingentgrenzen und Caching auf Ihrer Seite. Genau das unterschätzen die meisten selbst gebauten Galerien.

Der Weg ohne Code

Zeigen Sie einen Kanal oder eine Playlist als Galerie – ohne Data API, Schlüssel oder Kontingente.

Elfsight Video Gallery ausprobieren

Ein vollständiges Beispiel: eine Playlist mit Produktvideos

Ein typischer Anwendungsfall: ein Player, daneben eine Liste Ihrer Produktvideos und Analysedaten zu jeder Wiedergabe. Erstellen Sie den Player einmal, rendern Sie Ihre Liste als Buttons mit data-id-Attributen und rufen Sie beim Klick loadVideoById auf. Laden Sie bei ENDED die nächste ID Ihrer Liste, damit die Playlist weiterläuft. Senden Sie die Ereignisse video_start und video_complete mit dem Videotitel an Ihre Analytics. Alles andere – Vorschaubilder, Titel, Reihenfolge der Videos – stammt aus Ihren eigenen Daten, und genau das liefern die Data API oder ein Galerie-Widget.