The new JavaScript video embed code

We have developed another approach based on lazy-loading that you may prefer.


Adding one of your videos to one of your site’s pages is called embedding it. This simply means copying a snippet of code (the embed code) that we provide within our professional online video platform and then pasting it into your site. Then, when someone requests that page, the video appears within our provided player.

Naturally, loading that video player takes a small amount of time. As well as loading any assets the player needs, it needs to load its own code and styles - and also to perform automated tests on the request.

If you have multiple videos embedded on a page (we recommend just having one) this overhead is multiplied.

While the overhead is generally quite small, it is important that web pages load quickly and so we investigated how we could improve how our video player is embedded.

We investigated different approaches, including constructing the entire player on your page. However this introduces new problems - such as when style-rules defined for your page conflict with style-rules set for our video player - and it does not solve the underlying problem (since the player’s assets still need to be loaded). All that changes is the loading is initiated on your page, rather than within ours (our iframe embed code).


We realised that the majority of videos hosted within the platform are not set to auto-play (ie play when the page is loaded). We recommend not using auto-play because on iOS devices (iPhone, iPad), Apple prohibits it.

Therefore it seemed silly loading the player and its assets immediately just in case it was watched. It would seem more sensible to only load those files when they were actually needed (when the viewer clicks play). This is a similar idea to how browsers lazy load images (meaning that they are only loaded when they are needed - not loaded just in case they will be needed).

That meant the only assets that actually needed to be loaded immediately were the video’s poster frame image (to represent its content), a play button (to make clear it was indeed a video and not just a static image), and then a small bit of code to handle a click on that image. The combined total size was tiny. We discounted the size of the poster frame image (as that would be needed regardless of the method used to embed it) and the resulting code, served compressed, was just 3.7KB. We even reduced the number of http requests by including the play-button within the code, rather than loading it as a separate file).

Furthermore, since browsers cache files they have seen before, the code only needs to be downloaded once and so after the first request for our platform’s video player - on any page - it does not need to be downloaded again.

This suited all the requirements. The overhead of including a embedded video had been reduced to almost-zero - as low as it can be.

However of course what we have done is simply move the loading of the player and its assets from when your page loads to the time the viewer clicks play. And so while your pages load quicker, the time for the video to start playing (despite the files being served from a fast content delivery network) is fractionally increased. We thought that was still the better approach, because all visitors benefit from the faster loading page however not all visitors will watch a particular video.

Another slight annoyance is that on iOS, Apple do not permit videos to be played without the viewer having manually clicked on a play button. Auto-starting videos is blocked automatically. This means that viewers have to sometimes click twice on the lazy-loaded player - the first click swaps in the video player (which is then blocked from playing) and so it is the second click that starts the video playing.

How do I use it?

You will see it is structured a bit differently. It has two components: a ‘div’ tag, which acts like a placeholder, and a ‘script’ tag, which loads the code that listens for the click. For example it may look something like this:

<div class=“vidbeo-embed” data-id=“abcdefg” data-img=”https://example/image.jpg” data-width=“640” data-aspect=“16:9”></div><script>(function(d){var s=d.createElement(“script”);var i=d.getElementsByTagName(“script”)[0];s.src=””;s.async=true;i.parentNode.insertBefore(s,i)})(document);&lt;/script>

If we split the video embed code into its two parts, this is a bit clearer:

The placeholder div:

<div class=“vidbeo-embed” data-id=“abcdefg” data-img=”https://example/image.jpg” data-width=“640” data-aspect=“16:9”>

The script:

<script>(function(d){var s=d.createElement(“script”);var i=d.getElementsByTagName(“script”)[0];s.src=””;s.async=true;i.parentNode.insertBefore(s,i)})(document);&lt;/script>

The options

You will see our example div has four data attributes. We have listed the ones supported below:

data-id(Required) The unique id of the embedded item
data-img(Required) The image used to represent the embedded item, loaded from a global CDN
data-width(Optional) The width to embed the item at. If this is not provided, the embed code becomes responsive, filling the width of its container
data-aspect(Optional) The aspect-ratio to embed the item at (e.g. “16:9” or “4:3”). If this is not provided, it defaults to “16:9”
data-background(Optional) Whether to show a translucent panel to make the play button stand out more (useful for light backgrounds). If this is not provided, it defaults to false
data-autoplay(Optional) Whether to attempt to play it on-page-load. If this is not provided, it defaults to false

As you can see from the options above, making the new embed code responsive is as simply as removing the data-width attribute. With no width specified, the div will attempt to fill the width of its container. The player that then fills that div will in turn fill the available width - all the while maintaining the correct aspect ratio.

Note: If you are familiar with JavaScript, you actually only need to include the script tag on your page once. If you do only include it once, it needs to go at the bottom of your page. This is to ensure it loads after the div elements - so that it is able to find them.

Please contact us at [email protected] if you have any questions about embedding a video or indeed about our professional video hosting in general.

Updated: July 11, 2016