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:
- From a player(s) inside the Vidyard platform
- 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;
To learn more about readying the API, rendering players, and other advanced implementation options, see our advanced developer documentation.
Methods
Method | Description |
---|---|
.play() |
Start the player |
.pause() | Pauses the player |
.resume() | Resumes playback (alias to .play() ) |
.seek(position) |
The player position will be changed to the desired time. The position value is the desired player's position in seconds |
.scrubbing() |
Returns For example, you might use this method to distinguish a pause event as a result of timeline seeking versus the actual pause button. |
.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 name/language code) |
Enables captions. The language name and code values allow you to specify which caption to enable (e.g. If a value is not specified then this method will enable the first caption in the list. |
.disableCaption(language name/language code) |
Disables captions. The language name and code values allow you to specify which captions to disable (e.g. 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) | Select the audio track according to the index of available audio tracks. |
.addEvent(objectObject) | 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. |
.setPlaybackSpeed() | Sets the speed of playback. Only 2 , 1.5 , 1.25 ,1 & 0.5 are accepted decimal values. For example, setPlaybackSpeed(1.5) . |
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 |
---|---|
VidyardV4.api.GDPR.consent () | Sets consent for every player on your page to true or false. This method assigns consent on a per subdomain basis. |
VidyardV4.api.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:
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": "//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 }
Players 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. |