Taking the Videoly Widget API into use will give you more flexibility with the widget compared to the standard installation of Videoly, such as
- Carousel video display
- Multiple widgets are possible, even with different content preferences per widget
- Customization of thumbnails’ appearance
Installing the Widget API will take some development on your end, but should not take too long.
💡Please note: Widget API is available to all of our customers. Please get in touch with us at support@videoly.co if you have taken Widget API into use and would like us to hide the original widget.
💡Widget API customization limitations and YouTube compliancy
The player can’t be customized, as this is in breach of YouTube’s terms of service. More on this HERE.
Removing or altering YouTube play buttons on thumbnails or in the widget is not permitted by YouTube’s terms of service. You can use one of the three play button variants provided in the YouTube branding guidelines. Please familiarize yourself with the full list of customization limitations under YouTube's terms HERE.
The player will open in a pop-up. In-line playback is not supported.
Getting started
Example:
The sample below shows how to get video thumbnails and render them next to the product picture previews inside the gallery.
<!DOCTYPE html>
<html>
<head>
<!-- 1. Embed the Videoly Widget script to get all the functionality -->
<script src="api.videoly.co/1/.../quch.js" async></script>
</head>
<body>
<!-- 2. Choose the place where you'll render the set of videos -->
<div id="slider">
<div class="slide-item">some product picture 1</div>
<div class="slide-item">some product picture 2</div>
</div>
<script>
// 3. Put initial callbacks into the window, they'll be registered by the widget
window.videolyInitCallbacks = {
onVideoDataLoaded: [ handleVideoLoaded ]
};
function handleVideoLoaded(err, data) {
if (err) { } // handle error
const { videos, actions: { startPlayer, closePlayer } } = data;
renderer(videos, startPlayer, closePlayer);
}
// 4. Choose your favourite way to render videos
function renderer(videos, startPlayer, closePlayer) {
let slides = document.createDocumentFragment();
videos.forEach(video => {
const thumb = video.thumbs.default;
const slide = makeSlideItem(thumb);
// 5. Add data attribute (data-widget-api-video) to markup
// so we can confirm success rendering (!important)
slide.dataset.widgetApiVideo = true;
slide.addEventListener('click', () => startPlayer(video));
slides.append(slide);
});
const slider = document.getElementById('slider');
slider.append(slides);
}
function makeSlideItem(data) {...};
// 6. Now the new videos are ready to be played
</script>
</body>
</html>The following list provides more details about the sample above:
- You need to embed the Videoly Widget script to consume an API, so make sure that the script is in place before you proceed.
- The <div id="slider"></div> tag in this section identifies the location on the page where the videos will be placed. There is a slider with images already displayed on the page. Thumbnails should be placed within the slider near the existing images.
- To subscribe your callbacks on a particular event you need to place them inside the videolyInitCallbacks property of the window. This way you don't have to detect when the widget gets ready to expose API. The widget will automatically grab your callbacks and register them. Please note that you can place as many callbacks as you want, but this may impact performance.
- Now you can render data in any way that you prefer. In the sample above you see that new slides are created, event listeners are bound to every slide item, and slides are placed into existing <div id="slider"> via DocumentFragment. Please note that the startPlayer method takes the entire video object from the closure.
- We wait for you to add data-widget-api-video attribute to each HTML-element, which holds a particular video thumbnail. We gather these elements by data attributes to confirm that rendering has happened properly. It is important to ensure the statistics that we provide remain accurate.
- At this point, your slides can react to user clicks and play videos.
Functions
The Widget API supports the following syntax for subscribing to events
- videolyInitCallbacks property of window object (see above sample)
videolyInitCallbacks
We recommend this method of subscribing to events as you don't have to worry about the timing of the widget initialization. The Videoly widget will grab and register your callbacks on its initialization phase.
Syntax:
window.videolyInitCallbacks = {
onVideoDataLoaded: [
(err, data) => {...},
(err, data) => {...},
...
],
onVideoPlayStarted: [
(err, data) => {...},
(err, data) => {...}
],
'onEventName': [...callbacks]
}Events
Widget API fires events to notify your application of changes to the Videoly widget. The following list defines the events that the API fires.
1. onVideoDataLoaded
This event is fired whenever a Videoly Widget has finished loading videos and is ready to share or play videos.
If you want to render videos on your own, this particular event is the most important one to subscribe to.
The example below shows a sample function for handling this event:
window.videolyInitCallbacks = {
onVideoDataLoaded: [
(err, data) => {...},
(err, data) => {...},
...
]
}callback syntax:
(err, data): void;
/*
data object contains videos and actions properties;
videos is a collection of video items;
actions is an object with methods to work with videos.
*/
{
videos: [video1, video2, video3, ...],
actions: { startPlayer, closePlayer }
}
// startPlayer method takes entire video object
startPlayer(video1): void;
// closePlayer takes nothing
closePlayer(): void;The WidgetAPI also provides the video content from Videoly Pages (the videos on Category/Brands/Landing and other types of pages, if availble). The following callback-function can be used to fetch those:
widgetApi.registerInitialCallbacks({
onVideoDataLoaded: [onVideoDataLoadedCallback], // <-- for the videos on PDP
onPagesVideoDataLoaded: [onPageVideoDataLoadedCallback], // <-- for the videos on other than PDP pages
onVideoPlayStarted: [onVideoPlayStarted],
});2. onVideoPlayStarted
This event is fired whenever the widget starts to play a video.
window.videolyInitCallbacks = {
onVideoPlayStarted: [
(err, data) => {...},
(err, data) => {...},
...
]
}callback syntax:
(err, data): void;
// data object contains currentVideo property, which is a video item object
{ currentVideo: {...} }Data structures
Video item shape
{
id: String;
videoId: String;
duration: String; // "01:51"
genre: String;
language: String;
title: String;
thumbs: {
default: {
url: String;
},
medium: {...},
high: {...}
}
}Please let us know if you have any questions about Videoly Widget API. Reach out at support@videoly.co :)
Other options for installing the Videoly solution include Google Tag Manager and Shopify admin panel.