Elemento vs iframe
Como alcançar o player em cada modo de embed, e o que o iframe não expõe
O player vem em dois modos de embed, a escolha define todo o resto desta documentação: como você obtém uma referência ao player, e quais recursos consegue alcançar.
O elemento customizado coloca o <vturb-smartplayer> direto na sua página. O iframe carrega o player do converteai.net num contexto de navegação separado, e o SDK faz a ponte entre os dois.
Obter uma referência ao player
No elemento customizado, o player é um elemento no seu próprio DOM, então você o consulta:
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();
});
Ainda assim é preciso esperar o player:ready antes de chamar métodos — o elemento existe no DOM antes de o player por trás dele estar inicializado.
No iframe, sua página não alcança o interior. O SDK dispara o iframe:connected no <iframe>, subindo até o document, assim que a ponte sobe, e entrega um IframePlayer em 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 o evento dispara para cada player da página, o event.detail.id é o que permite distingui-los.
O player:ready nunca dispara no iframe, e o iframe:connected nunca dispara
no elemento. Código que espera o evento errado espera para sempre.
O que o iframe não expõe
Tudo abaixo funciona no elemento customizado e é indisponível — ou se comporta de outro jeito — dentro de um iframe. Não por omissão: as regras de cross-origin do navegador tornam a maior parte disso impossível.
| Recurso | Elemento | Iframe |
|---|---|---|
| Eventos e métodos | sim | sim, após o iframe:connected |
player:ready | sim | não, use iframe:connected |
| Variáveis CSS | sim | não, cross-origin |
fluid, pauseonetouch | sim | não |
injectUrlUpdater | sim | não |
| JS da headline | sim | sim, mas não sob CSP |
Se você precisa reestilizar o player, o elemento customizado é o único modo que permite isso. Estilização é o motivo mais comum para times abandonarem o embed em iframe.
Qual usar
Use o iframe quando você não controlar a página hospedeira o suficiente para adicionar uma tag de script, ou quando a página pertencer a uma plataforma que remove elementos customizados. Em todo o resto, o elemento customizado é o padrão melhor: mesma superfície de API, sem ponte para esperar, e a personalização e os atributos seguem disponíveis.