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.
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.playerindicates the data in the player objectresult.chapteris the numerical index of the chapter being played (e.g. the first video in a playlist = 1)result.eventis 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>