How to use the Vidyard Player API

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

API Script

Depending on whether you use Vidyard's inline and lightbox embed code or responsive embed code, the script used to control players differs slightly.

Locations you may retrieve these embed codes from, include:

  1. From a player(s) inside the Vidyard platform
  2. Through a request to the Vidyard dashboard API 
  3. As part integration process with the Vidyard GoVideo partner application

Inline & Lightbox Embed

<script type="text/javascript" id="vidyard_embed_code_[playerUUID] src="//play.vidyard.com/[playerUUID].js?v=3.1.1&type=inline"></script>
<script src="//play.vidyard.com/v0/api.js"></script>

Note the last line in script, <script src="//play.vidyard.com/v0/api.js"></script>. This is what includes the Player API on the page. It must follow the player embed script.

Responsive Embed

The Vidyard responsive embed code has the Player API built-in. Place the initial part of the script inside the header of your webpage.

Make note that the api script must come before all instances of the responsive embed on the page.

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"
/>

Referencing 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.


Example for querying a player

Inline and lightbox embed

// Returns a specified player
// Replace playerUUID with the UUID of the player you would like to control with the API
var player = new Vidyard.player("playerUUID"); 
player.play();

OR

// Returns all players with reference to one particular instance of a player
// Replace playerUUID with the UUID of the player you would like to control with the API
var players = new Vidyard.players(); 
players["playerUUID"].play();

Responsive embed

// 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;

Methods

Method
Description

.play()

Start the player from the beginning
.pause()
Pauses the player
.resume()
Resumes playback
.seek(position)

The player position will be changed to the desired time. The position value is the desired player's position in seconds

.setVolume(volume)
Set the player volume. The volume value is the desired player's volume represented between 0-1.
.toggleFullscreen()
Toggles player between fullscreen and original dimensions (whichever is the opposite of its current state).
.playChapter(index)
Play a designated video within the player. The index value is the desired video beginning at 0 for the first video.
.getCurrentChapter()
Returns the index of the current video within the player.
.enableCaption(language/label)
Enables captions. The language and label values allow you to specify which caption to enable. If a value is not specified then this method will enable the first caption.
.disableCaption(language/label)
Disables captions. The language and label values allow you to specify which captions to disable. If a value is not specified then this method will disable all captions that are showing.
.currentTime()
Returns player's current time as a decimal (in seconds)
.setAudiotrack(audioTrackIndex)
*responsive embed only
Select the audio track according to the index of available audio tracks.
.addEvent(objectObject)
*responsive embed only
It is recommended that users assign events through the Vidyard platform. However, if necessary, you may pass an object that includes an eventID, start time, duration, and chapterIndex to dynamically assign an event to a player.

const objectOptions = {  eventId: 37359,  start: 4,  duration: 4, chapterIndex: 0 }
Fullscreen events do not require a duration. Events cannot be pre-roll or post-roll.

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.

Method
Description
Vidyard.GDPR.consent ()
Sets consent for every player on your page to true or false.

This method assigns consent on a per subdomain basis.
Vidyard.GDPR.hasConsentOnReady (callback)
Callback receives true or false upon all player ready.

This function is intended to determine whether or not to display a consent prompt upon page load.

Example:

Vidyard.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": "//example.com/example_en.vtt"
          },
          {
            "name": "dansk",
            "language": "da",
            "is_default": false,
            "vtt_url": "//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
}

Events

Use events to craft responses in reaction to a player's behavior.

Event
Description
ready
Fired when the player has loaded on the web page.
play
This event fires when the player (re)commences playback.

Note: This function does not affect players when viewed on iOS devices.
pause
This event fires when the player is paused.
beforeSeek
This event fires immediately when the viewer seeks.

seek

This event fires when the viewer has completed a seek action to a new postion in the player.
playerComplete
This event fires when the end of the player is reached regardless of any seeking or pauses.
chapterComplete
This event fires when the end of a chapter is reached regardless of any seeking or pauses.
timeupdate
This event fires every ~100ms during playback.
volumeChange
This event fires when the volume is changed.

See our documentation for additional player API examples.

Was this article helpful?

Can’t find what you’re looking for? Please contact us below.

Email Vidyard Support
Why you didn't like the article?

If you would like Vidyard to get in contact with you regarding your feedback, please enter your email address.

  • No, Thanks