Using the Vidyard Player API

The Vidyard Player API allows developers to control the behavior of an embedded player via Javascript.

This document pertains to players that have been embedded using Vidyard's Responsive Embed Code.

The Player API Script

The Vidyard responsive embed code has the Player API script built-in.

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

1. From a player(s) inside the Vidyard platform
2. Through a GET request to the Vidyard dashboard API 

The responsive embed also allows for multiple instances of the same player on a given 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 API is 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.

// callback for a single player
// Add the UUID of the player you're trying to reference where indicated
window.onVidyardAPI = (vidyardEmbed) => {
 vidyardEmbed.api.addReadyListener((_, player) => {

console.log('player ready:', player.ready());
 console.log(player.uuid);
 // put your code here

}, "UUID")
 }

OR

// callback for multiple players
 window.onVidyardAPI = (vidyardEmbed) => {
 vidyardEmbed.api.addReadyListener((_, player) => {

console.log('player ready:', player.ready());
 console.log(player.uuid);
 // put your code here

}, ) // because we're looking for multiple players, we have no UUID specified here
 }

Querying a player

Players are referenced via their UUID. The UUID can be extracted from the player embed code or sharing page URL.

For example: http://embed.vidyard.com/share/oTDMPlUv--51Th455G5u7Q. The player UUID is oTDMPlUv--51Th455G5u7Q.

// returns a collection of players with the given UUID
var players = VidyardV4.api.getPlayersByUUID(UUID);
players[0].play();

OR

// get all players
var players = VidyardV4.players;

Note: to learn more about readying the API, rendering players, and other advanced implementation options, see our advanced developer documentation.

Methods

const objectOptions = { eventId: 37359, start: 4, duration: 4, chapterIndex: 0 }

GDPR-specific methods

These methods were implemented in order to enable customers to achieve GDPR compliance on webpages where Vidyard players exist.

The methods are used to communicate to players whether a visitor has consented to having identified view data passed to Vidyard. Note that Vidyard.GDPR.consent calls set to true persist in localStorage, so visitors to your webpage do not need to accept tracking on every page load.

When players do not receive consent, only completely anonymized viewing data will be passed to Vidyard.

Example:

VidyardV4.api.GDPR.hasConsentOnReady(function(consent) {
// Your callback logic goes here
});

Return player properties

Use player.metadata to return information about the player (title, length, description, public custom attributes, etc). This data is available after the ready event has fired. null is returned otherwise.

Example Response

{
  "chapters_attributes": [
    {
      "video_attributes": {
        "description": null,
        "name": "nature",
        "tags": [],
        "thumbnail_urls": {},
        "captions": [
          {
            "name": "English",
            "language": "en",
            "is_default": true,
            "vtt_url": "https://example.com/example_en.vtt"
          },
          {
            "name": "dansk",
            "language": "da",
            "is_default": false,
            "vtt_url": "https://example.com/example_da.vtt"
          }
        ]
      }
    }
  ],
  "custom_attributes": [
    {
      "attribute_type": "String",
      "is_public": true,
      "list_options": null,
      "name": "test_public",
      "value": "Test public"
    },
    {
      "attribute_type": "Number",
      "is_public": true,
      "list_options": null,
      "name": "test_public",
      "value": 10678
    }
  ],
  "description": "",
  "height": 360,
  "length_in_seconds": 123,
  "name": "player name",
  "tags": [],
  "visitorID": "string",
  "width": 640
}

Player Events

Build custom logic around your viewers' interactions with a Player.

player.on('ready', function () {
  console.log('Player is ready!');
});

player.on('play', function (eventTime) {
  console.log('The video started playing from second' + eventTime);
});

player.on('pause', function () {
  console.log('Viewer paused the video');
});

player.on('beforeSeek', function (event) {
  console.log('Viewer seeked at second ' + event.start); 
});

player.on('seek', function (seekTimes) {
  console.log('Viewer seeked from second ' + seekTimes[0] + ' to second ' + seekTimes[1]);
});

player.on('chapterComplete', function (chapterIndex) {
  console.log('Viewer finished watching chapter ' + (chapterIndex + 1));
});

player.on('timeupdate', function (eventTime) {
  console.log('Video time at second ' + eventTime);
});

player.on('volumeChange', function (volume) {
  console.log('Viewer set volume to ' + (volume * 100) + '%');
});

player.on('lightboxClose', function () { 
  console.log('Viewer closed the player'); 
});

player.on('metadata', function(args) {
   const metadata = args[0];
   console.log('Video metadata ready, and contains:' + metadata);
});

// or with destructuring args
player.on('metadata', ([metadata]) => {
  console.log('Video metadata ready, and contains' + metadata)
})