Elemento vs iframe
Cómo alcanzar el reproductor en cada modo de incrustación, y qué no expone el iframe
El reproductor viene en dos modos de incrustación, y la elección define todo lo demás en esta documentación: cómo obtienes una referencia al reproductor y qué funciones puedes alcanzar.
El elemento personalizado pone <vturb-smartplayer> directamente en tu página. El iframe carga el reproductor desde converteai.net en un contexto de navegación separado, y el SDK tiende el puente entre ambos.
Obtener una referencia al reproductor
En el elemento personalizado, el reproductor es un elemento de tu propio DOM, así que lo consultas:
const player = document.querySelector("vturb-smartplayer");
player.addEventListener("video:play", (event) => {
console.log("video:play");
// the player reference is available on the event
console.log(event.target);
// use it to call the player methods
event.target.play();
});
Aun así hay que esperar a player:ready antes de llamar métodos — el elemento existe en el DOM antes de que el reproductor detrás de él esté inicializado.
En el iframe, tu página no alcanza su interior. El SDK dispara iframe:connected en el <iframe>, subiendo hasta document, en cuanto el puente está arriba, y te entrega un IframePlayer en event.detail.player:
// don't call methods before the connection:
// window.vturbSdk.get("PLAYER_ID") returns undefined until then,
// and window.vturbSdk itself is undefined until the SDK script loads
document.addEventListener("iframe:connected", (event) => {
// identify which player connected
if (event.detail.id !== "PLAYER_ID") return;
const player = event.detail.player;
// the iframe player is connected now
player.fullscreen();
});
// or, listening on the iframe element itself
const iframe = document.getElementById("ifr_PLAYER_ID");
iframe.addEventListener("iframe:connected", (event) => {
const player = event.detail.player;
// do something
});
Como el evento se dispara para cada reproductor de la página, event.detail.id es lo que permite distinguirlos.
player:ready nunca se dispara en el iframe, y iframe:connected nunca se dispara en el
elemento. El código que espera el equivocado espera para siempre.
Qué no expone el iframe
Todo lo de abajo funciona en el elemento personalizado y no está disponible — o se comporta distinto — dentro de un iframe. No por omisión: las reglas cross-origin del navegador hacen imposible la mayor parte.
| Función | Elemento | Iframe |
|---|---|---|
| Eventos y métodos | sí | sí, tras iframe:connected |
player:ready | sí | no, usa iframe:connected |
| Variables CSS | sí | no, cross-origin |
fluid, pauseonetouch | sí | no |
injectUrlUpdater | sí | no |
| JS del titular | sí | sí, pero no bajo CSP |
Si necesitas reestilizar el reproductor, el elemento personalizado es el único modo que lo permite. El estilo es la razón más común por la que los equipos abandonan la incrustación en iframe.
Cuál usar
Usa el iframe cuando no controles la página anfitriona lo suficiente como para añadir una etiqueta de script, o cuando la página pertenezca a una plataforma que elimina elementos personalizados. En todo lo demás, el elemento personalizado es el mejor punto de partida: la misma superficie de API, sin puente que esperar, y la personalización y los atributos siguen disponibles.