YouTube iframe API: integrazione siti
La YouTube iframe API è una libreria JavaScript che permette di controllare programmaticamente il player YouTube embeddato su un sito: avviare, fermare, ascoltare eventi, conoscere lo stato di riproduzione. È lo strumento per chi vuole creare esperienze interattive avanzate intorno ai video.
Use case tipici
Quando serve: quiz interattivi che si attivano a determinati timestamp, analytics personalizzate sul tempo di visione, player sincronizzato con elementi pagina, autoplay su scroll, gating contenuti (richiedi email dopo 30 secondi), integrazione learning management system.
Setup di base
Si carica lo script iframe_api.js, poi si definisce la callback onYouTubeIframeAPIReady. Dentro la callback si istanzia un new YT.Player passando l'ID del div target e i parametri (videoId, width, height, events). Eventi disponibili: onReady, onStateChange, onPlaybackQualityChange, onError.
Stati del player
YT.PlayerState restituisce: -1 unstarted, 0 ended, 1 playing, 2 paused, 3 buffering, 5 cued. Ascoltare onStateChange e reagire ai cambi è il pattern più comune. Per esempio: registrare evento analytics quando state = 0 (video completato).
Procedura passo-passo
- Inserisci un div placeholder nella pagina con id="player".
- Carica lo script iframe_api.js prima di chiudere body.
- Definisci la funzione onYouTubeIframeAPIReady globale.
- Dentro la funzione istanzia new YT.Player('player', {...}).
- Passa videoId, width, height, playerVars (parametri URL).
- Aggiungi events: onReady, onStateChange.
- In onReady opzionalmente avvia con player.playVideo().
- In onStateChange leggi event.data per lo stato.
- Aggiungi logica custom (analytics, gating, sync).
- Testa cross-browser e cross-device.
Errori comuni e come risolverli
- Script caricato dopo l'istanza: causa errore "YT is undefined"; carica sempre prima.
- Callback non globale: onYouTubeIframeAPIReady deve essere su window.
- Player istanziato due volte: causa errori; verifica con if (player) destroy prima.
- Autoplay bloccato: browser bloccano autoplay senza mute; aggiungi mute: 1.
- Errori cross-origin: con iframe nascosto in localStorage rischi blocchi; usa origin parameter.
Domande frequenti
D: L'API funziona con youtube-nocookie?
R: Sì, basta usare host: 'https://www.youtube-nocookie.com' nei params.
D: Posso usare l'API anche su YouTube Shorts?
R: No, gli Shorts non sono embeddabili tramite API standard.
D: Quanto costa la YouTube iframe API?
R: Gratuita senza limiti specifici di chiamate.
Hai bisogno di aiuto?
Se vuoi crescere il tuo canale YouTube con il supporto del team di G Tech Group, scrivici tramite il modulo di contatto.