Métodos

Todo método de abajo exige el reproductor inicializado. En el elemento personalizado eso significa esperar player:ready; en el iframe, iframe:connected. Llamados antes, pueden lanzar error.

addEventListener

Suscribe un evento del reproductor. Misma firma que el método del DOM, incluido el objeto de opciones.

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

options.once quita el listener después de que se dispara una vez. Vale la pena en cualquier cosa que deba pasar una sola vez, porque la alternativa es acordarte de quitarlo tú mismo:

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

Quita un listener añadido con addEventListener. Misma firma que el método del DOM: pasa el mismo tipo de evento y la misma función. Guarda una referencia a la función, porque una función escrita inline no se puede volver a pasar. Si la añadiste con capture: true, pasa capture: true aquí también.

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 un listener que debe ejecutarse una sola vez, options.once de addEventListener lo quita por ti.

displayHiddenElements

Revela elementos cuando la reproducción pasa de un tiempo. Útil para llamadas a la acción que no deben verse desde el principio.

Parámetros

• time: number — cuándo revelar, en segundos.
• selectors: string[] — selectores CSS de los elementos a revelar.
• options.display?: string — el valor de display a aplicar. Por defecto block.
• options.persist?: boolean — mantenerlos visibles en cargas posteriores.
• options.callback?: () => void — se ejecuta tras revelar los 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 o sale de pantalla completa. Sin argumento, alterna.

Parámetros

• mode?: "on" | "off" — el estado a establecer.

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

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

mute

Silencia el audio.

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

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

unmute

Quita el silencio del audio.

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

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

onTime

Ejecuta un callback cuando la reproducción alcanza un tiempo. Más barato y más claro que filtrar cada video:timeupdate a mano.

Parámetros

• time: number — cuándo ejecutar, en segundos.
• callback: () => void — qué ejecutar.
• options?: object — opciones adicionales.

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

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

play

Inicia la reproducción.

Tres salidas, en orden de preferencia:

1. Llama a play() desde un gesto real del usuario.
2. Confirma que la reproducción empezó con video:play, en vez de depender del retorno de play().
3. Activa SmartAutoPlay en el panel de VTurb, que inicia el vídeo silenciado y le quita el silencio en la primera interacción.

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 la reproducción.

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

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

seek

Salta a un tiempo dado.

Parámetros

• time: number — el tiempo objetivo, en segundos.

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

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

setVolume

Define el volumen.

Parámetros

• volume: number — entre 0.0 y 1.0. Los valores fuera del rango se limitan.

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

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

speed

Define la velocidad de reproducción.

Parámetros

• speed: number — la nueva velocidad, donde 1 es la normal.

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

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

urlUpdater

Recibe una URL y la devuelve con los parámetros de conversión y seguimiento añadidos. Úsalo cuando tu página arma el enlace de destino y quieres que la conversión sea atribuible.

Parámetros

• url: string — la 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);
});

Mira Parámetros de conversión en URLs para saber qué acaba en la URL y por qué.

injectUrlUpdater

Registra una función que reescribe cada URL a la que apunta el reproductor — botones de llamada a la acción, anclas, imágenes. El reproductor la llama cada vez que necesita una URL.

Parámetros

• updater: (url: string, element?: HTMLElement) => string — recibe la URL original y, cuando existe, el elemento al que pertenece. Devuelve la 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();
  });
});