Métodos

Todo método abaixo exige o player inicializado. No elemento customizado isso significa esperar o player:ready; no iframe, o iframe:connected. Chamados antes, podem lançar erro.

addEventListener

Assina um evento do player. Mesma assinatura do método do DOM, incluindo o objeto de opções.

const player = document.querySelector("vturb-smartplayer");

// wait for the player before calling any method
player.addEventListener("player:ready", () => {
  player.setVolume(0.5);

  player.addEventListener("video:play", () => {
    console.log("video started playing");
  });
});

O options.once remove o listener depois que ele dispara uma vez. Vale usar em qualquer coisa que deva acontecer só uma vez, porque a alternativa é lembrar de remover o listener você mesmo:

// removed automatically after it fires once
player.addEventListener(
  "video:ended",
  () => {
    unlockNextContent();
  },
  { once: true },
);

// without `once`, you have to clean up yourself
const onEnded = () => {
  unlockNextContent();
  player.removeEventListener("video:ended", onEnded);
};

player.addEventListener("video:ended", onEnded);

removeEventListener

Remove um listener adicionado com addEventListener. Mesma assinatura do método do DOM: passe o mesmo tipo de evento e a mesma função. Guarde uma referência à função, porque uma função escrita inline não pode ser passada de novo. Se você a adicionou com capture: true, passe capture: true aqui também.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  // keep a reference: removing takes the same function
  const onTimeUpdate = (event) => {
    console.log("video:timeupdate", event.detail.time);
  };

  player.addEventListener("video:timeupdate", onTimeUpdate);

  player.addEventListener("video:ended", () => {
    player.removeEventListener("video:timeupdate", onTimeUpdate);
  });
});

Para um listener que deve rodar uma única vez, o options.once do addEventListener o remove por você.

displayHiddenElements

Revela elementos quando a reprodução passa de um tempo. Útil para chamadas para ação que não devem aparecer desde o começo.

Parâmetros

• time: number — quando revelar, em segundos.
• selectors: string[] — seletores CSS dos elementos a revelar.
• options.display?: string — o valor de display a aplicar. Padrão block.
• options.persist?: boolean — mantê-los visíveis em carregamentos futuros.
• options.callback?: () => void — roda depois de revelar os elementos.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  // reveal elements matching `.hidden` after 30 seconds
  player.displayHiddenElements(30, [".hidden"]);

  // several selectors, a custom display value and a callback
  player.displayHiddenElements(60, ["#cta-button", ".special-offer"], {
    display: "flex",
    callback: () => console.log("elements are visible"),
  });

  // keep them visible across page reloads
  player.displayHiddenElements(120, [".product-recommendation"], {
    persist: true,
  });
});

fullscreen

Entra ou sai da tela cheia. Sem argumento, alterna.

Parâmetros

• mode?: "on" | "off" — o estado a definir.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.fullscreen("on");
});

mute

Silencia o áudio.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.mute();
});

unmute

Tira o áudio do mudo.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.unmute();
});

onTime

Executa um callback quando a reprodução alcança um tempo. Mais barato e mais claro do que filtrar todo video:timeupdate na mão.

Parâmetros

• time: number — quando executar, em segundos.
• callback: () => void — o que executar.
• options?: object — opções adicionais.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.onTime(30, () => {
    console.log("the video reached 30 seconds");
  });
});

play

Inicia a reprodução.

Três saídas, em ordem de preferência:

1. Chame play() a partir de um gesto real do usuário.
2. Confirme que a reprodução começou com o video:play, em vez de depender do retorno do play().
3. Ative o SmartAutoPlay no painel do VTurb, que começa o vídeo mudo e tira o mudo na primeira interação.

const player = document.querySelector("vturb-smartplayer");
const button = document.getElementById("play-button");

player.addEventListener("player:ready", () => {
  // call play() from a user gesture, not on load
  button.addEventListener("click", () => player.play());
});

pause

Pausa a reprodução.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.pause();
});

seek

Salta para um tempo.

Parâmetros

• time: number — o tempo alvo, em segundos.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.seek(30); // 30 seconds in
});

setVolume

Define o volume.

Parâmetros

• volume: number — entre 0.0 e 1.0. Valores fora do intervalo são limitados.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.setVolume(0.5);
});

speed

Define a velocidade de reprodução.

Parâmetros

• speed: number — a nova velocidade, onde 1 é a normal.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.speed(1.5);
});

urlUpdater

Recebe uma URL e devolve com os parâmetros de conversão e rastreamento anexados. Use quando você monta o link de destino e quer que a conversão seja atribuível.

Parâmetros

• url: string — a URL a decorar.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  const url = player.urlUpdater("https://example.com/checkout");

  // https://example.com/checkout?<conversion and tracking params>
  console.log(url);
});

Veja Parâmetros de conversão em URLs para o que entra na URL e por quê.

injectUrlUpdater

Registra uma função que reescreve toda URL que o player aponta — botões de chamada para ação, âncoras, imagens. O player a chama sempre que precisa de uma URL.

Parâmetros

• updater: (url: string, element?: HTMLElement) => string — recebe a URL original e, quando existe, o elemento a que ela pertence. Devolve a URL a usar.

const player = document.querySelector("vturb-smartplayer");

player.addEventListener("player:ready", () => {
  player.injectUrlUpdater((url, element) => {
    const next = new URL(url, window.location.href);

    next.searchParams.set("utm_source", "player");

    return next.toString();
  });
});