Introduction

Here's the place where you can find all info about how to use player API while embedding it.

Structure

All player API calls can be divided into two categories: Actions (to make action on player, like play, seek, pause) and Subscriptions (to subscribe and react on events that come from player). For the list of actions and subscriptions go here.

Actions

To call actions you must have video ready, like that:

playerAPI.onReady(() => {
  playerAPI.seek({ time: 10 });
});
Copy

Some actions have limitations, for ex. you cannot simply call playerAPI.play() as first play action, but you can do it as reaction to some manual event (like button click and so on). It's browser limitation, so just use autoplay if you want to be able to start the video right away. So keep that in mind.

Subscriptions

Every subscription has a kind of "unsubscribe" function that's returned when you subscribe on particular action:

const unsubscribeOnPause = playerAPI.onPause(() => {
  console.info('Video paused!');
  // handle event once, so unsubscribe right away
  unsubscribeOnPause();
});

console.info('Do something here before unsubscribe');

// Don't need to get pause events anymore
unsubscribeOnPause();
Copy

Also, every event from the player has playerInfo (check Usage -> Call API using DOM events for more info) that allows to distinguish events from different players.

Usage

Call API using API instance proxy

To get player API proxy instance you should wait until window.voomlyEmbedPlayerPreloader is defined and call:

const playerAPI = window.attachVoomlyPlayer(
  /*
   * Root element to attach
   */
  embedPlayerElement,
  /*
   * Id of the video/funnel
   */
  embedVideoId,
  /*
   * Type of embed, video/funnel
   */
  type, // "v" | "f"
  /*
   * Ratio of the video/funnel
   */
  ratio, // string | "auto"
  /*
   * Presentation type of the video/funnel
   */
  presentation, // 'floatingModal' | 'openInModal' | undefined
  /*
   * Color of loading spinner
   */
  spinnerColor // string | undefined
);
Copy

It will attach player to a given div or get player API instance of previously attached one. You will get Proxy object that already checks if API is ready to use, so you just need to check if the player is ready to call any player actions or subscriptions.

Call API using API instance (advanced)

To get non proxied player API instance, you can do

const playerAPI = window.voomlyEmbedPlayerApp.getPlayerExternalAPIByContainer(embedPlayerElement);
Copy

or

const playerAPI = window.voomlyEmbedPlayerApp.getPlayerExternalAPIById(videoId);
Copy

But it will return player API instance only(!) when the player was attached. To do that subscribe to that event (you should wait until window.voomlyEmbedPlayerPreloader is defined):

window.voomlyEmbedPlayerPreloader.onAttached(videoId, ({ api: playerAPI }) => {
  console.info('Get API instance here');
});
Copy

Also, you must check if API instance is ready to use before accessing player API methods and subscriptions, like that:

playerAPI.onAPIReady(() => {
  playerAPI.onReady(() => {
    playerAPI.seek({ time: 10 });
  });
});
Copy

So, as result you will have:

window.voomlyEmbedPlayerPreloader.onAttached(videoId, ({ api: playerAPI }) => {
  playerAPI.onAPIReady(() => {
    playerAPI.onReady(() => {
      playerAPI.seek({ time: 10 });
    });
  });
});
Copy

It feels "a bit" cumbersome for just to call an API method, so it's much better to use proxy instead, that guarantees that API instance is initialized and player is attached.

Also, player API instance could be destroyed when there are no connected DOM instance, so in that case all API actions/subscriptions will not work. So, be sure that player's DOM node still exists after all player API calls.

Bonus: To get player API from proxy object you can do:

const playerAPINotProxyInstance = playerAPIProxy.getDevInstance();
Copy

In most cases you will not need that, the only case is when you need to check the API, but proxy have been created with wrong target before player was loaded.

Call API using DOM events

You don't need to have access to player API instance itself if you would like to subscribe to player events. You just need access to the player DOM node. So to subscribe events using DOM node just do:

const playerDOMElement = document.querySelector(
  '{selector to the player wrapper} > div.voomly-embed'
);
// ...or just document.querySelector(".voomly-embed") if you have single embed on the page

playerDOMElement.addEventListener('voomly:video:seeked', ({ payload }) => {
  console.info('Payload', payload);
});
Copy

Also, you can subscribe to DOM events using window or document object, just do

window.addEventListener(
  'voomly:video:paused',
  ({
    payload,
    payload: {
      playerInfo: { id, instanceId },
    },
  }) => {
    if (id === '{videoIdHere}') {
      console.info('Handle event here', payload);
    }
  }
);
Copy

Also, instanceId allows to distinguish players if you have multiple ones with the same video on the same page.

Call API using iframe

To call embed API that's located in iframe you need to do:

iframeDOMElement.contentWindow.postMessage(
  { eventName: 'voomly:video:play' },
  'https://embed.voomly.com'
);
Copy

To subscribe player events that come from iframe just do:

window.addEventListener('message', (event) => {
  if (event.origin !== 'https://embed.voomly.com') {
    return;
  }

  const { data } = event;

  if (data.eventName === 'voomly:video:timeUpdate') {
    if (data.payload.playerInfo.id === '{videoIdHere}') {
      const currentTime = data.payload.time;

      console.info('Handle event here', data.payload);
    }
  }
});
Copy