Player API

Quick start

Load the script, point it at your iframe, and call methods on the returned player. Every method returns a promise.

<iframe id="video" src="https://app.visiroll.com/v/VIDEO_ID"
        allow="autoplay; fullscreen; picture-in-picture"></iframe>

<script src="https://app.visiroll.com/player.js"></script>
<script>
  var player = new Visiroll.Player(document.getElementById("video"));

  player.on("ended", function () {
    console.log("the viewer finished the video");
  });

  player.play();
</script>

Commands sent before the iframe finishes loading are queued and delivered as soon as it is ready, so calling play() immediately after construction is safe.

The iframe

The constructor accepts an iframe element or a CSS selector. The allowattribute matters: without autoplay, a programmatic play() is refused by the browser, and without fullscreen the fullscreen button does nothing.

var player = new Visiroll.Player("#video");        // selector
var player = new Visiroll.Player(iframeElement);   // element

Copy a ready-made embed from the video’s Share tab in the studio.

Methods

player.getDuration().then(function (seconds) {
  console.log("duration", seconds);
});

player.setVolume(0.4)
  .then(function (volume) { console.log("volume is now", volume); })
  .catch(function (error) { console.error(error); });

Events

Subscribe with on(name, listener) and remove with off(name, listener), or off(name) to drop every listener for that event. Each listener receives a single data object.

Call player.destroy() when you remove the iframe, to detach the listeners.

Worked example

A common pattern: play inside a modal, keep a custom mute button outside the player, and unlock the next step only once the video has actually finished.

var player = new Visiroll.Player("#video");
var soundButton = document.querySelector(".sound-btn");

player.on("loaded", function () {
  player.setMuted(true);
  player.play();
});

soundButton.addEventListener("click", function () {
  player.getMuted().then(function (muted) {
    player.setMuted(!muted);
    soundButton.classList.toggle("is-muted", !muted);
  });
});

player.on("volumechange", function (data) {
  soundButton.classList.toggle("is-muted", data.muted);
});

player.on("ended", function () {
  closeModal();
  unlockReward();
});

Coming from Vimeo

The API deliberately mirrors the shape of the Vimeo SDK. In most integrations the change is the script URL and the constructor.

- <script src="https://player.vimeo.com/api/player.js"></script>
+ <script src="https://app.visiroll.com/player.js"></script>

- var player = new Vimeo.Player(iframe);
+ var player = new Visiroll.Player(iframe);

Method names, promise returns, and the on / off pattern match. Two differences worth knowing:

• getPaused() replaces Vimeo’s getPaused() with the same meaning, but there is no getEnded() — listen for the ended event instead.
• Event payloads carry only the fields listed above, so data.seconds becomes data.currentTime.

Domains and security

The player only accepts commands from pages whose origin appears in that website’s allowed domains, wildcards included. Replies and events are posted back to that exact origin, never to *. A page that is not on the list can neither embed the video nor control it.

While developing against a local server, add the development host — for example localhost — as an allowed domain on the website, and remove it before the site goes live.