Trigger Javascript actions at video milestones with progress events

June 21, 2023 18:37
Updated

The Vidyard Player API allows you to trigger javascript actions in-browser when a video hits specific milestones during playback (% of video watched). These milestones are known as progress events.

Most commonly, progress events are used to push video engagement data into third-party applications. But you can trigger any javascript action that suits your purposes.

Learn more about the Vidyard Player API

Embed a video

The Player API is built in to Vidyard's embed code. Simply embed a video on a page, and the API is ready to use.

You can obtain the embed code from any of these locations:

From any video(s) inside the Vidyard platform
Through a GET request to the Vidyard dashboard API

Place the API script from the embed code in the header of your webpage. Make sure that the API script comes before all instances of the embed code on the page.

<!-- The script tag should live in the head of your page if at all possible -->
<script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>

<!-- Put this wherever you would like your player to appear -->
<img
class="vidyard-player-embed"
src="https://play.vidyard.com/"playerUUID".jpg"
data-uuid="playerUUID";
data-v="4"
data-type="inline"
/>

Ensure the Player API and players are ready

The API script contains an async attribute. Async ensures that the API becomes available, but does not interfere with other aspects of the page load.

Because the API loads asynchronously, use the onVidyardAPI callback so that any scripts you've added to the page know when the Player API becomes available.

// registerProgressEvents is the name of the function that interacts with the Vidyard API
// this can be defined anywhere in your code
window.vidyardEmbed
  ? initApp(window.vidyardEmbed)
  : (window.onVidyardAPI = (vyApi) => registerProgressEvents(vyApi));

We also want to ensure that the player(s) on the page are loaded and ready to accept incoming messages from the API. We do that with addReadyListener.

vidyardEmbed.api.addReadyListener(function(data, player) { ... })

Trigger a callback at specific milestones

Use vidyardEmbed.api.progressEvents to specify the following:

The action you want to make (e.g. post data to a third party application)
The data you want to call from the resulting player object
The viewing milestones at which the event should fire (e.g. 1, 25, 50, etc)

function registerProgressEvents(vidyardEmbed) {
  vidyardEmbed.api.progressEvents(function (result) {
    sendToThirdParty(result.player.uuid, result.chapter, result.event);
  }, [1, 25, 50, 75, 95]);
}

Available data from the player object

You can use any of the data from the Vidyard player object as part of your milestone triggers. See an example of the full player object.

result.player indicates the data in the player object
result.chapter is the numerical index of the chapter being played (e.g. the first video in a playlist = 1)
result.event is the percentage of the video that has been viewed

{
   player: {
     play: function () {...},
     seek: function (position) {...},
     ...,
     metadata: {
       description: "",
       name: "player name",
       chapters_attributes: [...],
     ...
  },
  chapter: 1,
  event: 25
}

Example

<html>
<head>
  <script type="text/javascript" async src="https://play.vidyard.com/embed/v4.js"></script>
  <script type="text/javascript">
    function sendToThirdParty(playerUuid, chapter, percentProgress) {
      // send data to an analytics backend
  }

  function registerProgressEvents(vidyardEmbed) {
    vidyardEmbed.api.addReadyListener(function(data, player) {
      vidyardEmbed.api.progressEvents(function (result) {
       sendToThirdParty(result.player.uuid, result.chapter, result.event);
      }, [1, 25, 50, 75, 95]);
    });
  }

  window.vidyardEmbed
    ? registerProgressEvents(window.vidyardEmbed)
    : (window.onVidyardAPI = (vidyardEmbed) => registerProgressEvents(vidyardEmbed));
  </script>
</head>

<body>
  <div id="video-container">
    <img class="vidyard-player-embed" src="https://play.vidyard.com/hTgyffdMUrGFU7amYcZGpc.jpg"
      data-uuid="CPgzCyMA7ufgRumDFF" data-v="4" data-type="inline" />
  </div>
</body>
</html>

Embed a video

Ensure the Player API and players are ready

Trigger a callback at specific milestones

Available data from the player object

Example

Need support