VdoPlayer JS www.vdocipher.com

VdoPlayer Embed code

The embed code

<div id="embedBox"></div>
<script>
  (function(v,i,d,e,o){v[o]=v[o]||{}; v[o].add = v[o].add || function V(a){ (v[o].d=v[o].d||[]).push(a);};
if(!v[o].l) { v[o].l=1*new Date(); a=i.createElement(d), m=i.getElementsByTagName(d)[0];
a.async=1; a.src=e; m.parentNode.insertBefore(a,m);}
})(window,document,"script","https://cdn-gce.vdocipher.com/playerAssets/1.4.6/vdo.js","vdo");
vdo.add({
  otp: "REPLACE WITH OTP",
  playbackInfo: btoa(JSON.stringify({
    videoId: "REPLACE WITH VIDEO ID"
  })),
  theme: "9ae8bbe8dd964ddc9bdb932cca1cb59a",
  container: document.querySelector( "#embedBox" ),
});
</script>

The embed code consists of three parts:

  1. create a container for video
  2. load the init script
  3. Setting up global vdo object to hold loaded videos.
  4. Initialize with video information.

The above is a generic embed code that should work almost everywhere. In more specialized cases, you may be interested in using it differently to suit your workflow.

Note: For Angular or React or any other SPA, check how to setup on SPA

Getting reference to the video player

The above script creates a window.vdo object which is an object which maintains the list of all loaded videos. vdo.getObject() will return an array consisting of all video instances in the order in which it was created. If you are creating multiple video instances without page reload (via ajax), you should take care to refer to the correct video object. In most cases, it will the last element in the returned array.

var videos = vdo.getObject();
var video = videos[videos.length - 1];

JS API reference

Reference is the place we aggregate all methods and properties in an organised way. It is not supposed to be illustrative but is the exhaustive list. It contains everything that you can use in a tabular format.

Use the link on the header of this page to explore the API reference.

Server reference

If you are looking for API reference for managing your VdoCipher account or to obtain auth tokens via API, head over to the server API page.

VdoPlayer Embed code

The embed code

<div id="embedBox"></div>
<script>
  (function(v,i,d,e,o){v[o]=v[o]||{}; v[o].add = v[o].add || function V(a){ (v[o].d=v[o].d||[]).push(a);};
if(!v[o].l) { v[o].l=1*new Date(); a=i.createElement(d), m=i.getElementsByTagName(d)[0];
a.async=1; a.src=e; m.parentNode.insertBefore(a,m);}
})(window,document,"script","https://cdn-gce.vdocipher.com/playerAssets/1.4.6/vdo.js","vdo");
vdo.add({
  otp: "REPLACE WITH OTP",
  playbackInfo: btoa(JSON.stringify({
    videoId: "REPLACE WITH VIDEO ID"
  })),
  theme: "9ae8bbe8dd964ddc9bdb932cca1cb59a",
  container: document.querySelector( "#embedBox" ),
});
</script>

The embed code consists of three parts:

  1. create a container for video
  2. load the init script
  3. Setting up global vdo object to hold loaded videos.
  4. Initialize with video information.

The above is a generic embed code that should work almost everywhere. In more specialized cases, you may be interested in using it differently to suit your workflow.

Note: For Angular or React or any other SPA, check how to setup on SPA

Getting reference to the video player

The above script creates a window.vdo object which is an object which maintains the list of all loaded videos. vdo.getObject() will return an array consisting of all video instances in the order in which it was created. If you are creating multiple video instances without page reload (via ajax), you should take care to refer to the correct video object. In most cases, it will the last element in the returned array.

var videos = vdo.getObject();
var video = videos[videos.length - 1];

JS API reference

Reference is the place we aggregate all methods and properties in an organised way. It is not supposed to be illustrative but is the exhaustive list. It contains everything that you can use in a tabular format.

Use the link on the header of this page to explore the API reference.

Server reference

If you are looking for API reference for managing your VdoCipher account or to obtain auth tokens via API, head over to the server API page.

Single page websites

Applicable to Angular, React, Vue etc.

Step 1: setup the global script

Single page websites have the advantage of loading most scripts and other assets only once. Navigating the pages do not reload any new assets.

Add the VdoCipher script in your index.html file.

<script src="https://dev.vdocipher.com/playerAssets/1.4.6/vdo.js"></script>

Step 2: use the VdoPlayer class in your component

The component could be an React componentDidMount() or a Angular 1 controller or Angular 2 ngAfterViewInit(). At this point, you will have access to the window.VdoPlayer class. A new instance of this class need to be created to hold the video player.

var video = new VdoPlayer({
  otp: "REPLACE WITH OTP",
  playbackInfo: btoa(JSON.stringify({
    videoId: "REPLACE WITH VIDEO ID"
  })),
  theme: "9ae8bbe8dd964ddc9bdb932cca1cb59a",
  // the container can be any DOM element on website
  container: document.querySelector( "#embedBox" ),
});

// you can directly call any methods of VdoPlayer class from here. e.g:
// video.addEventListener(`load`, () => {
//   video.play(); // this will auto-start the video
//   console.log('loaded');
// });

Getting reference to the video player

The global window.vdo object will no longer keep track of the created video player instances. The instance returned by the VdoPlayer constructor will have to maintained in your script in order to refer to the video player. If the container DOM element is cleared and the reference to player is lost, all associated data will be cleared by the garbage collector.

FAQ: What is wrong with previous full embed code?

The full embed code is supposed to be contained in itself. It consists of four parts:

  1. create a container for video
  2. load the init script
  3. Setting up global vdo object to hold loaded videos.
  4. Initialize with video information.

It tries to do all this asynchronously such that loading other website assets should not be affected. There is a global callback which can be used to listen to script load events. You need a window.onVdoCipherApiReady method which will be called on init. In a single-page website, the individual component is loaded async. It is not recommended to create and listen for global callback methods or to create global object. Therefore, we recommend to use the above alternative method to add video player.

Custom HTML on player

Custom HTML can be added to player using player JS. The injectThemeHtml() can be used to inject HTML or styles dynamically into the player.

Basic setup:

Note: Assuming the player script is already loaded, otherwise wrap this in a window.onVdoCipherApiReady() method.

// var videos = window.vdo.getObject();
// var video = videos[videos.length - 1];

// OR

// var video = new VdoPlayer({ ... });

// listen for the theme to load
video.addEventListener(`mpmlLoad`, () => {
  video.injectThemeHtml('<p>Hello world</p>');
});

Note that the player elements as well as the HTML injected by the above scripts are all parts of your website DOM and not inside the iframe. This means that any website CSS will be applied to your injected HTML. It also means that you can reference your injected HTML with just regular DOM APIs such as getElementById

Example: Adding brand logo as a moving watermark

The player creates a relative positioned div inside the container and uses it to create multiple absolute positioned elements. We shall create styles for the watermark and position at the bottom right.

p.watermark: {
  position: absolute;
  bottom: 20px;
  right: 20px;
}
// assuming video contains the reference to video instance
video.addEventListener(`mpmlLoad`, () => {
  video.injectThemeHtml('<p class="watermark">Hello world</p>');
});

Note that everything is in your DOM so you can basically do anything with it. Here we try to move around the watermark every 2 seconds

// get a reference to your video container
var container = document.querySelector('.embedBox');

// get reference to all watermarks
var watermarks = document.querySelectorAll('.watermark');
setTimeout(() => {
  for (var i = 0; i < watermarks.length; i++) {
    var mark = watermarks[i];
    var contWidth = container.offsetWidth;
    var contHeight = container.offsetHeight;
    mark.left = (contWidth - mark.offsetWidth) * Math.random();
    mark.top = (contHeight - mark.offsetHeight) * Math.random();
  }
}, 2000);

Keyboard shortcuts

Viewers like to have a comfortable video player where the features are easily accessible at familiar positions. You might want to configure keyboard actions for your player. For example, you might want the player to pause and play when spacebar is pressed. Left and right keys might be used to go forward and backward in time.

Starting with version 1.2.x, we have added a key-bindings feature which you can use to configure these in your video player.

vdo.add({
  ...
  plugins: [{
    name: 'keyboard',
    options: {
      preset: 'default'
    }
  }]
})

Default is the name of a internal preset of keyboard bindings that is supposed to work in most cases and help you get setup quickly.

Adding custom keyboard bindings

vdo.add({
  ...
  plugins: [{
    name: 'keyboard',
    options: {
      preset: 'default',
      bindings: {
        'Up' : (player) => player.volume += 0.2,
        'Down' : (player) => player.volume -= 0.2,
      },
    }
  }]
})

Default preset

'Space': (player) => (player.status === 1) ? player.pause() : player.play(),
'}' : (player) => player.playbackRate += 0.2,
'{' : (player) => player.playbackRate -= 0.2,
'f' : (player) => player.fullscreen(!player.isFullscreen),
'Left' : (player) => player.currentTime -= 20,
'Right' : (player) => player.currentTime += 20,

Immersive mode video

If you have a mode in your web application where the video player is the most prominent element and is supposed to respond to keyboard events irrespective of current focus of user, we call this an immersive mode.

The keyboard plugin is not build for an immersive mode by default. It assumes there might be other videos in the webpage and other elements which might be need to respond to keyboard. If the viewer clicks outside, video is no longer able to listen to keyboard events.

The keyboard plugin creates a virtual container and keeps that in focus when it detects a click event. This container can listen to keyboard events when in focus. This way, keyboard events is captured only when the viewer has directly clicked on the video.

If you are trying to design an immersive mode application, you can always create your own event listeners on document.body and trigger playback actions. Get in touch with our support and we can assist you in the setup.

Controlling keyboard using API

Q. What if I directly bind the javascript keyboard events myself with VdoPlayer API?

If you are building a custom immersive experience for your users, this might be what you should be doing. However, in a standard embed of video player, it might cause issues when there are multiple player or when there are multiple widgets on the same page. To avoid such conflicts, the VdoPlayer configures it with the virtual container instead of the document body. This way, you can have multiple videos and only the last interacted video will detect keyboard events. You can do all this in javascript using our API.

Also, the keyboard plugin only binds to keydown event and has no provision for listening for other keyboard events. Triggering for other keyboard events is possible if you create your own keyboard listeners.

Unless you have an immersive video experience, you should not listen to keyboard events in higher level DOM elements such as document or body.

Styling the VdoPlayer

This is a beta product Please exercise caution while using theplayer.io to create themes and use on a production system. It is recommended to create backup of any HTML and SASS files that you create from theplayer.io.

The themes are controlled by theplayer.io which is a standalone product of Vdocipher. You can login with your Vdocipher account and explore existing themes. You can choose to edit an existing theme to suit your needs.

The themes are constructed by a collection of HTML attributes which can be used to connect theme elements such as buttons and icons to player actions. You can use any method in the VdoPlayer Class with a binder such as mpml-on-click.

Using custom events

Theplayer.io interface is built for creating new overlays and call-to-actions and similar user engagement tools. You can easily create buttons which show up at the right time. You can set it up to trigger javascript events in your website.

Step 1: Put this button in your theme:

<button mpml-show="currentTime | gt 130" mpml-on-click="myCustomEvent">Buy now</button>

The button will show on video after 130 seconds. Another example:

<button mpml-show="currentTime | inrange '45-50,130-135'" mpml-on-click="myCustomEvent">Buy now</button>

The button will now show up between the seconds 45-50 and the seconds 130 to 135.

Step 2: When viewer clicks on this button you can trigger your own actions. Listen for the event by creating a new property in the vdoPlayer object itself.

video.myCustomEvent = () => {
  // pause the video and
  // prompt for the credit card info
}

Change Log

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[1.3.2] - 2017-09-27

Added

  • quality control API for compatible videos
  • keyboard and SPA documentation
  • totalCoveredArray to show playback and rewinds
  • more internal events for error tracking
  • clipstat plugin for reporting errors
  • allow setting theme in page URL and iframe embeds
  • docs version updater in side panel

    Fixes

  • documentation structure styles
  • fixed android playback issue for some videos
  • theme disabled for iOS to enable iOS 8 and 9
  • better theme loader CDN
  • hide default focus outline on video
  • better error messages on failure
  • prompt zenplayer for watermarked android videos
  • fix multiple initialization script inclusion

[1.2.0] - 2017-08-24

Added

  • keyboard plugin for controlling player with keyboard shortcuts
  • presets for keyboard shortcuts
  • documentation should have a link to latest version
  • mpml events will be emiited such as mpml:click or mpml:mouseover
  • focus method on vdoPlayer

    Fixes

  • fix buffering parameters for reliable playback
  • increase cdn fallback to 30 seconds
  • correct CORS issue when switching CDN

[1.1.2] - 2017-08-18

Fixes

  • reduce defaultBandwidth to enable quickstart on dash
  • show buffering instead of play until loaded

[1.1.0] - 2017-08-14

Added

  • debug option for editing theplayer.io themes
  • event for theme load event mpmlLoad
  • injectThemeHtml() method for injecting custom html
  • calculate the isBuffering property
  • add statusText property for string version of status

Fixes

  • reduce rebufferingGoal for dash player
  • correct bufferLength for some html5 players
  • do not idle when buffering or when error
  • better errorMessage in dash playback
  • handle fallback flash player error on Chrome Mac

[1.0.0] - 2017-08-03

Added

  • add ended and playlist features
  • CDN fallback in case of DNS issue
  • calculate totalPlayed and totalCovered

[0.9.1] - 2017-07-13

Added

  • speed control
  • fullscreen
  • seeked and seeking event
  • add version prefix in script URL
  • show poster image in DASH player
  • added esdoc documentation
  • add error screen to display errors
  • supports IE>9

Fixes

  • Bug fixes with mid-rolls
  • ios safari playback

[0.9.0] - 2017-06-17

Added

  • advertisement support via Google IMA SDK
  • play HTML5 secure playback without flash
  • can play vdocipher flash DRM as fallback
  • better device detection

[0.0.1] - 2016-12-10

Added

  • changelog
  • specifications