Methods

Every method below needs the player to be initialized. On the custom element that means waiting for player:ready; on the iframe, for iframe:connected. Called earlier, they may throw.

addEventListener

Subscribes to a player event. Same signature as the DOM method, including the options object.

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 removes the listener after it fires once. It is worth using for anything that should happen a single time, because the alternative is remembering to remove the listener yourself:

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

Removes a listener added with addEventListener. Same signature as the DOM method: pass the same event type and the same function. Keep a reference to the function, because one written inline cannot be passed again. If you added it with capture: true, pass capture: true here too.

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

For a listener that should run a single time, options.once on addEventListener removes it for you.

displayHiddenElements

Reveals elements once playback passes a given time. Useful for calls to action that should not be visible from the start.

Parameters

• time: number — when to reveal, in seconds.
• selectors: string[] — CSS selectors for the elements to reveal.
• options.display?: string — the display value to apply. Defaults to block.
• options.persist?: boolean — keep them visible on later page loads.
• options.callback?: () => void — runs after the elements are revealed.

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

Enters or exits fullscreen. Without an argument it toggles.

Parameters

• mode?: "on" | "off" — the state to set.

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

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

mute

Mutes the audio.

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

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

unmute

Unmutes the audio.

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

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

onTime

Runs a callback when playback reaches a given time. Cheaper and clearer than filtering every video:timeupdate yourself.

Parameters

• time: number — when to run, in seconds.
• callback: () => void — what to run.
• options?: object — additional options.

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

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

play

Starts playback.

Three ways around it, in order of preference:

1. Call play() from a real user gesture.
2. Confirm that playback started with video:play instead of relying on the return value of play().
3. Turn on SmartAutoPlay in the VTurb dashboard, which starts the video muted and unmutes it on the first interaction.

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

Pauses playback.

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

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

seek

Jumps to a given time.

Parameters

• time: number — the target time, in seconds.

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

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

setVolume

Sets the volume.

Parameters

• volume: number — between 0.0 and 1.0. Values outside the range are clamped.

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

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

speed

Sets the playback rate.

Parameters

• speed: number — the new rate, where 1 is normal speed.

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

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

urlUpdater

Takes a URL and returns it with the conversion and tracking parameters appended. Use it when you build a destination link yourself and want the conversion to be attributable.

Parameters

• url: string — the URL to decorate.

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

See URL conversion params for what ends up in the URL and why.

injectUrlUpdater

Registers a function that rewrites every URL the player links to — call-to-action buttons, anchors, images. The player calls it whenever it needs a URL.

Parameters

• updater: (url: string, element?: HTMLElement) => string — receives the original URL and, when there is one, the element it belongs to. Returns the URL to use.

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