Vidyard Embed Code
The Vidyard Embed code is published in 2 variants, a script tag and a UMD module.
Script Tag
Exposed as main
in package.json
and also served from our CDN https://play.vidyard.com/embed/v4.js
.
The script tag is auto executing, it will scan the document for Vidyard embed placeholder images and render the players.
<!-- The script tag should live in the head of your page if at all possible -->
<script src="https://play.vidyard.com/embed/v4.js" type="text/javascript" async></script>
<!-- Put this wherever you would like your player to appear -->
<img
style="max-width: 100%;"
class="vidyard-player-embed"
src="https://play.vidyard.com/Cse5Fqy1CpUWqYdtikKrFy.jpg"
data-uuid="Cse5Fqy1CpUWqYdtikKrFy"
data-v="4"
data-type="inline"
/>
Options For Rendering Players
- type = ['lightbox', 'inline']
- aspect = 'landscape' which is 16:9 aspect ratio
- all player options, you can find all player options from the following link https://knowledge.vidyard.com/hc/en-us/articles/360009879754-Use-query-strings-to-override-player-settings
- The default options are
- disable_popouts = 1
- type = 'inline'
Unstructured Metadata
To pass unstructured metadata to the player use the data-vydata
attribute, the one caveat here is data attributes use the DOMStringMap
format which limits the characters we can use for the key, hence we pass all of the complex nested data as a stringified and URI encoded JSON.
Listening to Ready
The embed script is loaded asynchronously hence we notify the client code on the embed code availability:
Simple client code example:
// initApp is the client's function that interacts with the Vidyard API
// this needs to be defined before the v4 embed script is added to the page
window['onVidyardAPI'] = (vyApi) => initApp(vyApi);
Or check for the presence of the API global and fallback to the onVidyardAPI
// initApp is the client's function that interacts with the Vidyard API
// this can be defined anywhere in the client code
window.vidyardEmbed
? initApp(window.vidyardEmbed)
: (window.onVidyardAPI = (vyApi) => initApp(vyApi));
Or with promises:
// this can be defined anywhere in the client code
new Promise(res => window.vidyardEmbed
? res(window.vidyardEmbed)
: (window['onVidyardAPI'] = (vyApi) => res(vyApi))
).then((vyApi) => {
console.log('The Vidyard API is ready ', vyApi);
});
For IE9+ we also dispatch an onVidyardAPI
custom event on document
that can be listened on instead of using the global callback:
// initApp is the client's function that interacts with the Vidyard API
window.vidyardEmbed
? initApp(window.vidyardEmbed)
: document.addEventListener('onVidyardAPI', ({ detail: vyApi }) => initApp(vyApi));
UMD Module
Exposed as the module
filed in package.json
, bundling tools like Webpack should use this filed.
The UMD is also available from our CDN, https://play.vidyard.com/embed/v4.umd.js
, it will not auto execute when imported, requiring the client to render the players by calling vidyardEmbed.api.renderPlayer
or vidyardEmbed.api.renderDOMPlayers
.
Public API Documentation
The Vidyard global object and the named exports of the module expose the follwoing APIs:
VidyardV4 = {
api: {
GDPR: { consent, hasConsentOnReady },
addReadyListener,
getPlayersByUUID,
progressEvents,
renderDOMPlayers,
renderPlayer,
}
}
GDPR.consent([true|false])
- Sets consent for every player on your page to true or false.
- This method assigns consent on a per subdomain basis.
import vidyardEmbed from '@vidyard/embed-code';
userHasGivenConsent() { // embed page code
vidyardEmbed.api.GDPR.consent(true);
}
GDPR.hasConsentOnReady(cb)
- Callback receives
true
orfalse
upon all player ready. - This function is intended to determine whether or not to display a consent prompt upon page load.
import vidyardEmbed from '@vidyard/embed-code';
vidyardEmbed.api.GDPR.hasConsentOnReady((consent) => {
if (!consent) {
showConsentPrompt(); // embed page code
} else {
greet(); // embed page code
}
});
addReadyListener(cb[, uuid])
- Callback to call when the player is ready.
- The
uuid
is optional filter for individual players. - If omitted the callback will apply to all players on the page.
import vidyardEmbed from '@vidyard/embed-code';
vidyardEmbed.api.addReadyListener((_, player) => {
console.log('the player is ready', player);
player.seek(20);
player.play();
});
getPlayersByUUID(uuid)
- Returns an Array of all of the initialized players that are match the given
uuid
. - If the same player is embedded multiple times the retuned Array will have a player object for each one.
- After you get player object, you can call the player api like play(), resume(), seek(), ready() etc. For more details about player api, please visit https://knowledge.vidyard.com/hc/en-us/articles/360009871054-How-to-use-the-Vidyard-Player-API
import vidyardEmbed from '@vidyard/embed-code';
const players = vidyardEmbed.api.getPlayersByUUID('xxxxxxxxxxxxxxxxxxxxxx');
players[0].ready();
progressEvents(cb)
- Allows you to trigger a given callback a player hits a certain viewing milestone (% of video watched).
- The passed in callback gets a
{ player, chapter, event } = result
object. - For more details, please visit https://knowledge.vidyard.com/hc/en-us/articles/360009870114-Trigger-Javascript-actions-at-certain-viewing-milestone-with-progress-events
import vidyardEmbed from '@vidyard/embed-code';
vidyardEmbed.api.addReadyListener((_, player) => {
vidyardEmbed.api.progressEvents(({ chapter, event, player }) => {
const { name } = player.metadata.chapters_attributes[chapter].video_attributes;
console.log(`${name}: ${event}%`);
if (event === 4) {
player.pause();
}
}, [1, 2, 3, 4, 25, 50, 75, 100]);
}, 'xxxxxxxxxxxxxxxxxxxxxx');
renderDOMPlayers([container])
- Renders all player in a given container, if a container is omitted it defaults to
document
. - The
<script src="https://play.vidyard.com/embed/v4.js">
version of the embed code will auto execute and render all players in the DOM by calling this method.
Or player in a specific container:
import vidyardEmbed from '@vidyard/embed-code';
const playersContainer = document.getElementById('video-content');
vidyardEmbed.api.renderDOMPlayers(playersContainer);
renderPlayer(options)
- Renders the player programmatically.
- The
options
can either be anHTMLImageElement
in the DOM or a configuration object. - The configuration object needs to have the an
uuid
and acontainer
properties.
import vidyardEmbed from '@vidyard/embed-code';
const placeholderImage = document.querySelectorAll('img.vidyard-player-embed')[0];
vidyardEmbed.api.renderPlayer(placeholderImage);
Or using a data object:
import vidyardEmbed from '@vidyard/embed-code';
vidyardEmbed.api.renderPlayer({
uuid: 'xxxxxxxxxxxxxxxxxxxxxx',
container: document.getElementById('player-container');
// optional
type: 'lightbox',
aspect: 'landscape',
vydata: encodeURIComponent(JSON.stringify({location: 'here', more: 'yes'}),
// ...
// any additional parameters
});
destroyPlayer(player)
- Removes the player from the DOM.
- Unsubscribes all progress events.
- Removes the player model from
Vidyard.players()
.