Videoly Widget API

How to get increased flexibility and control of the player using Videoly’s Widget API

Taking the Videoly Widget API into use will give you more flexibility with the widget compared to the standard implementation of Videoly, such as   

    • Bigger thumbnails (3 size options as provided by YouTube)
    • Carousel video display
    • Multiple widgets possible, even with different content preferences per widget
    • Customisation of  thumbnails’ appearance  

With the Widget API, you will get the same statistics and MyVideoly video management possibilities as with the standard widget as well as the integration to your Google Analytics.

Installing the Videoly 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.

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:

    1. You need to embed the Videoly Widget script to consume an API, so make sure that the script is in place before you proceed.
    2. 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.
    3. 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.
    4. 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.
    5. 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.
    6. At this point, your slides can react to user clicks and play videos.

Functions

The Widget API supports two different syntaxes for subscribing to events

  • videolyInitCallbacks property of window object (see above sample)
  • registerCallbacks method of VideolyWidget object 

1. 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]
}

2. registerCallbacks

This method is exposed to the Videoly widget object right after the DOM is built and videolyInitCallbacks have been initialized. With this method, you can easily register new callbacks in the middle of the widget working process.

Syntax:

window.VideolyWidget.regiterCallbacks(
    'onVideoPlayStarted',
    [(err, data) => {...}, (err, data) => {...}]
);

window.VideolyWidget.regiterCallbacks('onEventName',[...callbacks]);

Events

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

2. onVideoPlayStarted

This event is fired whenever the player 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.

Was this article helpful?