YouTube IFrame API: panduan praktis

Poin utama

• Muat https://www.youtube.com/iframe_api sekali saja dan buat pemutar di dalam onYouTubeIframeAPIReady.

• Kontrol pemutaran dengan playVideo, pauseVideo, seekTo, mute, dan loadVideoById.

• Tanggapi onStateChange dan onError untuk melacak pemutaran dan melewati video yang rusak.

• IFrame API tidak memerlukan kunci; menampilkan daftar video saluran atau playlist memerlukan YouTube Data API dengan kunci dan kuota.

Muat API dan buat pemutar

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

Metode yang umum digunakan

Event

onReady, onStateChange (memutar, dijeda, selesai), onError. Gunakan untuk melacak jumlah tayangan atau memulai video berikutnya.

Kapan Anda tidak memerlukan API

Untuk galeri, playlist, atau feed saluran di halaman pemasaran, API berarti banyak kode yang harus dipelihara.

Cara tanpa kode

Tampilkan video YouTube dalam pemutar dengan playlist — tanpa kode API.

Coba Elfsight Video Gallery

Cara API dimuat

IFrame API hanyalah satu skrip. Setelah selesai dimuat, skrip ini memanggil fungsi global bernama onYouTubeIframeAPIReady — buat pemutar Anda di sana. Muat skrip sekali per halaman, meskipun Anda memiliki beberapa pemutar, dan buat setiap pemutar pada elemennya sendiri.

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

Status pemutar

Dengarkan onStateChange dan bandingkan event.data dengan konstanta ini.

Buat tombol putar kustom

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

Jika Anda menyembunyikan kontrol YouTube, Anda bertanggung jawab menyediakan kontrol yang aksesibel — dukungan keyboard dan label.

Lacak pemutaran dan video yang selesai ditonton

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

Tangani error

Dengarkan onError dan lewati ke video berikutnya dalam daftar Anda saat terjadi error.

IFrame API vs. YouTube Data API

IFrame API mengontrol pemutaran video yang sudah Anda ketahui. Untuk menampilkan daftar unggahan sebuah saluran atau video dalam playlist, Anda memerlukan YouTube Data API yang terpisah — dengan kunci API, batas kuota harian, dan caching di sisi Anda. Bagian inilah yang paling sering diremehkan pada galeri buatan sendiri.

Cara tanpa kode

Tampilkan saluran atau playlist sebagai galeri tanpa Data API, kunci, atau kuota.

Coba Elfsight Video Gallery

Contoh lengkap: playlist video produk

Kasus penggunaan yang umum: satu pemutar, daftar video produk Anda di sebelahnya, dan analitik untuk setiap pemutaran. Buat pemutar sekali, tampilkan daftar Anda sebagai tombol dengan atribut data-id, lalu panggil loadVideoById saat diklik. Pada ENDED, muat ID berikutnya dalam daftar agar playlist terus berjalan. Kirim event video_start dan video_complete ke analitik beserta judul videonya. Semua yang lain — thumbnail, judul, urutan video — berasal dari data Anda sendiri, yang persis menjadi bagian yang disediakan oleh Data API atau widget galeri.