Get started with the Player API

Get started with the Player API

If you would like to control a player embedded on your site using JavaScript you can use our Player API.

Initially all your Player API requests will fail because your browser will block them. That's because your page and our page (our embed code) use different domains. To solve that, we have made a vpJS.request helper function which can be used to send messages to our player. You will need to save that function as a file (for example called vp.js) and/or include it on any page you want to call the Player API on. Or make your own equivalent.

Having done that, a window.vpJS object is then available.

vp.js

(function (vpJS, undefined) {
/*
* The iframe's domain
*
* @type {String}
*/
var iframeDomain = 'https://watch.vidbeo.com';
/*
* Make a request to a player embedded in an iframe on this page
*
* @method request
* @param {String} iframeId
* @param {String} functionName
* @param {Object} functionParameter
* @return {}
* @public
*/
vpJS.request = function (iframeId, functionName, functionParameter = null) {
if (typeof JSON.stringify !== 'function') {
// it is not possible to send the message without JSON support
return false;
}
// build the message
var messageObject = {};
messageObject.functionName = functionName;
messageObject.functionParameter = functionParameter;
messageObject.callbackName = null; // not needed
// JSON-encode it
var message = JSON.stringify(messageObject);
// send the message across domains by using postMessage
var iframe = document.getElementById(iframeId);
if (iframe) {
iframe.contentWindow.postMessage(message, iframeDomain);
}
};
})((window.vpJS = window.vpJS || {}));

If you expect to get data from our player, there needs to be a way for the interaction to work the other way too. We have done that using a callback function with an extended version of that file which you can use instead:

(function (vpJS, undefined) {
/*
* The iframe's domain
*
* @type {String}
*/
var iframeDomain = 'https://watch.vidbeo.com';
/*
* Initialise the player API for communicating with the iframes containing embedded players
*
* @method init
* @private
*/
function init() {
// attach an event listener for messages sent to this page by any iframe ...
if (window.addEventListener) {
window.addEventListener('message', receivedMessage, false);
}
}
/*
* A message has been received by this page
*
* @method receivedMessage
* @param {Object} message
* @return {}
* @private
*/
function receivedMessage(message) {
// check this message came from our iframe
if (message.origin !== iframeDomain) {
return false;
}
var messageData = message.data;
var messageObject = JSON.parse(messageData);
if (messageObject == null) {
return false;
}
// are all of the expected attributes present?
if (
!messageObject.hasOwnProperty('type') ||
!messageObject.hasOwnProperty('functionName') ||
!messageObject.hasOwnProperty('functionParameter')
) {
return false;
}
// check the type is supported
if (messageObject.type != 'callback') {
return false;
}
var alphaNumericRegEx = /^([a-zA-Z0-9]+)$/;
if (alphaNumericRegEx.test(messageObject.functionName) === false) {
return false;
}
// proceed to call it
var callback = new Function(
messageObject.functionName + '(' + messageObject.functionParameter + ')'
);
callback();
}
/*
* Make a request to a player embedded in an iframe on this page
*
* @method request
* @param {String} iframeId
* @param {String} functionName
* @param {Object} functionParameter
* @param {String} callbackName
* @return {}
* @public
*/
vpJS.request = function (
iframeId,
functionName,
functionParameter = null,
callbackName = null
) {
if (typeof JSON.stringify !== 'function') {
// it is not possible to send the message without JSON support
return false;
}
// build the message
var messageObject = {};
messageObject.functionName = functionName;
messageObject.functionParameter = functionParameter;
messageObject.callbackName = callbackName;
// JSON-encode it
var message = JSON.stringify(messageObject);
// send the message
var iframe = document.getElementById(iframeId);
if (iframe) {
iframe.contentWindow.postMessage(message, iframeDomain);
}
};
init();
})((window.vpJS = window.vpJS || {}));

Structure

All requests follow the same basic structure:

vpJS.request(elementId, action, parameter);

or

vpJS.request(elementId, action, parameter, callback);

Try it out

We will start by demonstrating the simplest action: playing a video.

Of course normally you would be listening for a click event, not using onclick. This is just a very simple example to demonstrate the concept. Just after the embed iframe on your page, put this line of HTML:

<a href="#play" onclick="vpJS.request('iframe_VIDEOID', 'play');">Play Video</a>

... making sure to replace VIDEOID with the actual id. If you are not sure what it is, simply look at your embed code and you want the long, random letters and numbers part.

Now let's look at the components of that function call set to run when 'Play Video' is clicked:

vpJS

This is just short for Vidbeo Player JS.

request

This is the name of the function the library makes available.

iframe_VIDEOID

This is needed in order for the library to know which element (the iframe) the message should be sent to. If your iframe does not have an ID, you will need to add one to it like id="iframe_VIDEOID"

And finally:

play

This is the action you want to perform using the Player API. Here we want to play the video.

Note: Two more parameters are supported (not included here because they are not applicable to the play action). Those are the parameter to pass to the action (for example the new volume, in the case of the volume action), and finally the name of a callback function.

So now if you refresh the page, you should hopefully see a link somewhere near the player on your page called 'Play Video'. Click on it. Does the video start playing?