Vidyard Embed Code

Vidyard Player embed and API

Table of Contents
- What is Vidyard Embed Code
- NPM Package
- Script Tag
- UMD module
- Embed Options
- Data attributes
- Listening to Ready
- Unstructured metadata
- Overriding the Player Instance
- Embed API
- GDPR.consent
- GDPR.hasConsentOnReady
- addReadyListener
- getPlayersByUUID
- progressEvents
- renderDOMPlayers
- renderPlayer
- destroyPlayer
- getPlayerMetadata
- Player API
- License

What is Vidyard Embed Code

The Vidyard embed code helps embed Vidyard players into web pages and applications. It provides programmatic playback control, the ability to listen on playback events, GDPR consent control and integration with third party MAP platforms.

In addition, the Vidyard Embed code is fully responsive (filling the width of the container element by default), it enhances SEO with JSON-LD tags and it improves the accessibility of the player on your page.

By default the Vidyard embed code has 2 components, the embed script and the placeholder image:
1. The Vidyard Embed script comes in 3 flavours: NPM Package, Script Tag and UMD module hosted on the Vidyard CDN. Only one version needs to be included to allow full access to all the players on that page.
2. The placeholder image is an tag that displays the thumbnail of the video and contains data attributes that control how the player is rendered. Each player uses a separate placeholder image.

The Vidyard Embed code is designed to be lightweight and asynchronous. The placeholder image reserves a place in the layout for the video player while minimizing impact on the loading performance of the page.

NPM Package

The Vidyard Embed code can be bundled as an NPM dependency into your project:

``bash
npm install --save @vidyard/embed-code


or using Yarn


yarn add @vidyard/embed-code
`

Then imported directly in your JavaScript:

`javascript
import VidyardEmbed from '@vidyard/embed-code';

// render all players from placeholder images in the document
VidyardEmbed.api.renderDOMPlayers();

// render a player programmatically, see method documentation below
VidyardEmbed.api.renderPlayer({...})
`

Script Tag


Served from the Vidyard Global Content Delivery Network at https://play.vidyard.com/embed/v4.js.

The script tag is auto executing. This means that on script load it will scan the document for Vidyard embed placeholder images and will replace them with Vidyard players.

`html




style="max-width: 100%;"
class="vidyard-player-embed"
src="https://play.vidyard.com/UUID.jpg"
data-uuid="UUID"
data-v="4"
data-type="inline"
/>
`

UMD Module


The UMD is also available from the Vidyard Global Content Delivery Network at 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.

`html




style="max-width: 100%;"
class="vidyard-player-embed"
src="https://play.vidyard.com/UUID.jpg"
data-uuid="UUID"
data-v="4"
data-type="inline"
/>


`

Embed Options

$3


Included as data attributes on the placeholder image (options must be prepended with data-):
- data-type: specifies the type of embedlightbox or inline
- data-uuid: the unique identifier string of the player
- data-aspect: the aspect ratio of the player landscape, portrait, height / width * 100 (custom value)
- all other player options, can be found in the Vidyard knowledge base.

$3

Note: This only applies to the Embed Script and UMD module embed types (not the NPM Package).

By default, the Embed Script Tag is loaded asynchronously by using the async attribute on the script tag. The client code is notified when the embed code has loaded and is ready to be used using the following methods.

For Internet Explorer 9 we dispatch an onVidyardAPI custom event on document that can be listened to instead of using the global callback:

`javascript
// initApp is the client's function that interacts with the Vidyard API
window.vidyardEmbed
? initApp(window.vidyardEmbed)
: document.addEventListener('onVidyardAPI', ({ detail: vyApi }) => initApp(vyApi));
`

Or by adding assigning a callback onto the global onVidyardAPI value that will be called once the embed script is loaded

`javascript
// 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);
`
It is a good idea to check for the presence of the API global and fallback to the onVidyardAPI

`javascript
// 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:

`javascript
// 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);
});
`

$3


To pass unstructured metadata to the player, use the data-vydata attribute. Data attributes use the DOMStringMap format which limits the characters we can use for the key, so all complex nested data is passed as a stringified and URI encoded JSON.

`javascript
const placeholderImg = document.querySelector("[data-uuid='UUID']");
placeholderImg.setAttribute(
"data-vydata",
encodeURIComponent(
JSON.stringify({
location: "here",
more: "yes"
})
)
);
`

$3


By default the embed code is pointing at the production instance of play.vidyard.com, this can be overridden by using the data-playbackurl attribute on the script tag.

`html

`

Or by setting a global variable before including the embed script.

`javascript
window.VIDYARD_PLAYBACK_URL = 'play-staging.vidyard.com';
`

Or by calling the debug method

`javascript
window.vidyardEmbed._debug.setPlaybackURL('play-staging.vidyard.com');
`




Embed API


The vidyardEmbed named export and the window.VidyardV4 object expose the following APIs:

`javascript
import vidyardEmbed from '@vidyard/embed-code';

const {
api: {
GDPR: { consent, hasConsentOnReady },
addReadyListener,
getPlayerMetadata,
getPlayersByUUID,
progressEvents,
renderDOMPlayers,
renderPlayer,
}
} = vidyardEmbed;
`

$3


- Sets consent for every player on your page to true or false.
- This method assigns consent on a per subdomain basis.

`javascript
import vidyardEmbed from '@vidyard/embed-code';

userHasGivenConsent() { // client page code
vidyardEmbed.api.GDPR.consent(true);
}
`

$3


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

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.GDPR.hasConsentOnReady((consent) => {
if (!consent) {
showConsentPrompt(); // client page code
} else {
greet(); // client page code
}
});
`

$3


- Callback to call when the player is ready.
- The data object is undefined for the ready event.
- The UUID is optional filter for individual players.
- If omitted the callback will apply to all players on the page.

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.addReadyListener((data, player) => {
console.log('the player is ready', player);
player.seek(20);
player.play();
});
`

$3


- Returns an Array of all of the initialized players that match the given UUID.
- If the same player is embedded multiple times the returned 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 the Vidyard Knowledgebase

`javascript
import vidyardEmbed from '@vidyard/embed-code';

const players = vidyardEmbed.api.getPlayersByUUID('UUID');
players[0].ready();
`

$3


- 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 the Vidyard Knowledgebase

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.addReadyListener((data, 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]);
}, 'UUID');
`

$3


- Renders all players in a given container, if a container is omitted it defaults to document.
- The Script Tag version of the embed code will auto execute and render all players in the DOM by calling this method internally.

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.renderDOMPlayers();
`

Or player in a specific container:

`javascript
import vidyardEmbed from '@vidyard/embed-code';

const playersContainer = document.getElementById('video-content');
vidyardEmbed.api.renderDOMPlayers(playersContainer);
`

$3


- Renders the player programmatically.
- The options can either be an HTMLImageElement in the DOM or a configuration object.
- The configuration object needs to have a uuid and a container properties.

Note: The renderPlayer API method will not work inside the ready event
as described above when using the standard v4.js script.
It will, however, work inside the ready event when using the UMD module or NPM package,
or using the standard v4.js script outside of the ready event (in which case, do not use the async attribute on the v4.js script tag).

`javascript
import vidyardEmbed from '@vidyard/embed-code';

const placeholderImage = document.querySelectorAll('img.vidyard-player-embed')[0];
vidyardEmbed.api.renderPlayer(placeholderImage);
`

Or using a data object:

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.renderPlayer({
uuid: 'UUID',
container: document.getElementById('player-container');
// optional
type: 'lightbox',
aspect: 'landscape',
vydata: encodeURIComponent(JSON.stringify({location: 'here', more: 'yes'}),
// ...
// any additional parameters
});
`

$3


- Removes the player from the DOM.
- Unsubscribes all progress events.
- Removes the player model from window.Vidyard.players().

`javascript
const player = api.getPlayersByUUID('pZovJVPRGJWs2scm3EZckY')[0];
api.destroyPlayer(player);
`

$3


- Fetches metadata for players that have not been rendered.
- Accepts a string UUID for the player.
- Returns a promise containing the player metadata object, if the player UUID is not valid the promise is rejected.

`javascript
import vidyardEmbed from '@vidyard/embed-code';

vidyardEmbed.api.getPlayerMetadata('UUID')
.then((metadata) => {
console.log(metadata);
})
.catch((e) => {
console.log('error fetching player metadata');
});
`

The schema of the Player Metadata object:

`typescript
interface Metadata {
chapters_attributes: Array<{
video_attributes: {
captions: any[];
description: string | null;
length_in_milliseconds: number;
length_in_seconds: number;
name: string;
sd_url: string;
status: string;
tags: any[];
thumbnail_urls: {
normal: string;
play_button: string;
play_button_small: string;
small: string;
};
};
}>;
custom_attributes: any[];
description: string;
height: number;
is_ai_video: boolean;
length_in_seconds: number;
name: string;
tags: any[];
uuid: string;
width: number;
}
`

Player API

Once a player is selected with any of the Embed API methods, the player API allows for control of the player and adding handlers for player events. Full documentation of the Vidyard Player API can be found in the Vidyard Knowledge Base.

`javascript
const players = VidyardEmbed.api.getPlayersByUUID(UUID);
const firstPlayer = players[0];

firstPlayer.play();

firstPlayer.on('playerComplete', () => {
console.log('the video was watched in full, hurray!');
});
``

License

The Vidyard Embed code is licensed under the MIT License.

> Copyright 2021 Buildscale Inc.
>
> Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
>
> The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
>
> THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.