Javascript API

Control the Buto player using our Javascript API
This version of the JavaScript API should be used in conjunction with our primary player (all accounts prior to May 2013 are served this player). Our new player is gradually being rolled out as features are added.

This tool is designed for web developers and as such you will need to be familiar with writing simple JavaScript to use it within your own website

You will only need to use it if you would like to do one of the following two things:

1. To use events triggered by time/click when you would like that event to be a call to a JavaScript function. An example would be to add an item to a shopping basket when an item in your video is clicked. You can configure these events very easily. Within your control panel, for each video, in the left-hand menu, simply click on ‘Events triggered by time’ or ‘Events triggered by click’.

2. If you would like to move the player’s controls (play, pause …) outside of the player.

Do you have any examples of it being used?

Listed below are some simple demonstrations we have made using our own sample videos.

As soon as the grey ‘loading’ graphic disappears, they are ready to use. You do not have to have this grey overlay on your own pages – we simply added it to make it clear that the player is ready to use:

To understand exactly what is going on within each example (especially if you would like to make something similar) we would recommend viewing the source code of each page using your browser’s ‘View/Page Source’ option. The HTML and JavaScript code is very simple, and indeed could be simplified further using external libraries such as jQuery.

How do I use it with my own videos?

The first stage is to embed one of your videos on your own web page using our recommended iframe embed code.

Now to permit communication between your video player and the Buto system, you will need to edit your video’s player settings (click on the ‘Videos’ tab in your control panel, and then on ‘Player settings’ in the left-hand menu) to enter the domain names you will be using the JavaScript API from. For example if your video is embedded on www.mycompany.com/example.html, you need to permit communication from www.mycompany.com. So simply enter www.mycompany.com in the relevant box, and click ‘Save’.

This is needed because JavaScript has built-in protection to prevent code being run across domains. To enable communication across domains we make use of the postMessage function included with all modern browsers (from Internet Explorer 8 onwards). We have made a simple Javascript library which includes all of the functions needed. Simply include this file at the bottom of your web page before the closing </body> tag. This automatically serves the latest version of the library from our CDN:

<script type="text/javascript" src="https://embed.buto.tv/javascript-player-api">
</script>

I need to host all JavaScript files on my own domain …

If you would like to host the library yourself, you are welcome to. Simply visit https://embed.buto.tv/javascript-player-api in your browser and download the JavaScript file you receive.

I’ve specified my permitted domain(s) and I’ve included that library on my page …

Now use the ‘Events triggered by time’ and ‘Events triggered by click’ options (found on each video’s page, in the left-hand menu). You can trigger JavaScript to run when a particular time is reached, or when a particular region/in-player advert is clicked.

We would suggest you begin by trying to make some very simple JavaScript run. Within your control panel, choose a sample video you can use for testing a new feature such as this. Click on ‘Events triggered by time’ in the left-hand menu, and then on the ‘Call JavaScript’ tab. Click on the link to ‘add a new JavaScript function’, type in:

alert('Hello World');

… and then enter 00:05 as the time-code you would like this to be run at.

Now if that very simple example works on your page, and you see the message ‘Hello World’ after your have watched your video for five seconds, you can then proceed to call your own functions.

Please note that we resrict the code you can execute directly to simple calls (such as to alert, or your own functions). If you try and manipulate the page’s DOM directly, you may find that your code may be removed – we’ll show this with [removed]. If you stick to calling functions that already exist on your page, you shouldn’t ever see this happen, so we recommend you do.

Alternatively you may prefer to keep all your JavaScript within your own site – and simply make use of Buto to notify you of the event happening. You can read more about how to this below.

Notification functions

Before the JavaScript API can be used to call functions on a player, or receive events from a player (triggered by time and/or click), it needs to confirm the player is ready.

As soon as a player loads on your page, it sends a message to confirm that it is ready. You will therefore need to implement the function butoEventUpdate in order to be notified when the player is ready. Here we remove our loading graphic as soon as the player is ready:

function butoEventUpdate(playlistId, videoId, attribute, value) {

	if (attribute == "ready" && value) {
		document.getElementById("blackout_screen").style.display = "none";
	}	

}

Our primary notification function is called butoEventUpdate. This notififies you when one of the player’s attributes change so that you can respond to this, should you need to. You will certainly need to respond to a change in the ‘ready’ state – this is the notification that your player is now ready to be controlled.

With all of our notification functions:

If you are viewing a video, the playlistId will be blank.
If you are viewing a playlist, the videoId contains the currently playing video’s id.

function butoEventUpdate(playlistId, videoId, attribute, value)

Attribute Value Examples
ready Boolean true, false
duration Float 130.3498
currentTime Float 2.12
Volume Float 0.5
playerStatus String unknown, ready, playing, paused, ended
videoId String ABCDE

function butoEventTimedJavaScript(playlistId, videoId, javaScriptId, timeCode, javaScriptCode)

This function is called when you request that some JavaScript be executed when a particular time-code is reached. You are free to leave the JavaScript code blank within the control panel when asked to enter it. If you implement this particular function, you could actually make use of this parameter to pass additional data your function may need, such as JSON-encoded product information. If this function is implemented, your entered JavaScript will not be executed as we will assume you will handle the event yourself.

function butoEventClickedIPA(playlistId, videoId, inPlayerAdvertId, timeCode, javaScriptCode)

This function is called when a link in one of your in-player adverts is clicked. The timeCode parameter holds the time-code when the link was clicked, should you need to know this.You are free to leave the JavaScript code blank within the control panel when asked to enter it. If you implement this particular function, you could actually make use of this parameter to pass additional data your function may need, such as JSON-encoded product information. If this function is implemented, your entered JavaScript will not be executed as we will assume you will handle the event yourself.

function butoEventClickedRegion(playlistId, videoId, clickableRegionId, cliclableRegionObjectName, javaScriptCode)

This function is called when a clickable region is clicked. The id and name of the object the region is positioned over are passed. You are free to leave the JavaScript code blank within the control panel when asked to enter it. If you implement this particular function, you could actually make use of this parameter to pass additional data your function may need, such as JSON-encoded product information. If this function is implemented, your entered JavaScript will not be executed as we will assume you will handle the event yourself.

How do I control the player as you do in your ‘External Controls’ demo?

If you are using the JavaScript API for adding external player controls, you can call functions such as play(), pause() and stop(), to control it. You would usually call these functions when the user performs certain actions. Such as when they click on your ‘play’ button, you would call the play() function to make the player play. So in conjunction with our check above, below you can see that as soon as the player is ready we loop through all buttons on the page, enabling them:

function butoEventUpdate(playlistId, videoId, attribute, value) {

	if (attribute == "ready" && value) {
		document.getElementById("blackout_screen").style.display = "none";

		var playerControlButtons = document.getElementsByTagName("button");

		for (var i=0; i<playerControlButtons.length; i++) {
			playerControlButtons[i].disabled = false;
		}
	}	

}

The next step in this example is to add buttons to let the user control the player. So we add an event listener …

function butoPlayerControlsAddEvent(id, eventName, eventHandler) {

   var element = document.getElementById(id);

   if (window.addEventListener) {
      element.addEventListener(eventName, eventHandler, false);
   }

   else {
      element.attachEvent("on"+eventName, eventHandler);
   }

}

… and then listen for clicks on each button we have placed on the page. For example, here we listen for a click on the ‘play’ button …

butoPlayerControlsAddEvent("play_button", "click", function(){

   butoPlayers["VIDEO_ID"].play();

});

The functions available to externally control the player are below:

function play(): void
function pause(): void
function stop(): void
function seek(time:number): void
function setVolume(volume:number): void
function getDuration(): number
function getCurrentTime(): number
function getVolume(): number
function getPlayerStatus(): string

In addition, if your player contains a playlist, you can use these additional functions to select the video within it:

function next(): void
function previous(): void
function skipTo(index:number): void

Notes:

The volume is a value between 0 and 1 – e.g. 0.5 represents 50%.

The player status is a string:
unknown
ready
playing
paused
ended

The duration is only available once a video file has been requested. This happens either when pre-buffering is turned on, since the video is requested as soon as the player appears on the page, or when the video is played by the user. It will report as 0s until one of these two things happens.

The video index is an integer 0 – 24 (since playlists can hold at most 25 videos). It is the index of the video to skip to within your playlist, with 0 being the first video.

How does your library know my video/playlist id?

When your web page is requested, the code within our library will look at your page and make a list of all Buto players embedded on the page (most of the time you will only have one, though this method offers the flexibility to support multiple ones). These are put into an array called butoPlayers. Each index in this array is its unique five character id.

Does it work with all web browsers?

No – due to the limitations of older browsers it will only work on relatively new ones that support HTML 5 standards.

It won’t work on Internet Explorer 6 or 7, so if you your viewers use these browsers we suggest you add a warning to those users to let them know they won’t be able to use your custom controls. The browser version can easily be detected with JavaScript. In the case of our demonstration pages, the loading graphic will never be removed because the notification the player is ready will never be received.

Will it work on mobile devices like the iPad?

No – for the time being we have restricted usage to the desktop Flash player which isn’t supported by Apple. The Flash player is installed on 98% of computers. In time, we will add mobile support where possible.

Will it work if my video is shared on other websites, like Facebook?

No – it will only work when (a) the page the video is embedded on contains our JavaScript library, which is needed to allow communication with the player, and (b) the website is permitted to communicate with the player by the addition of its domain in your player settings.

Even if you do enter http://www.facebook.com in your player settings as being permitted, it still would be blocked, because Facebook has very stringent security settings that prevent any external JavaScript from running.

We would suggest that if your player relies on using the JavaScript API, you disable sharing, since when the video is shared, it is likely this won’t work.

It doesn’t work …

First, try viewing one of our example pages – these are listed at the top of this section. Do these work? Does the grey loading graphic disaapear after a couple of seconds?

If our examples do not work, are you using a compatible web browser? It won’t work on Internet Explorer 7 or below.

If our examples do work, but your website does not, have you added the domain name(s) of that website to your player settings? If you can use either http://www.mycompany.com and http://mycompany.com (some websites support not using the ‘www’ prefix, while others do not) you will need to add both, separated by a space. Save your settings and try refreshing your page.

If you have added your domain name(s) to your player settings, try just triggering some very simple JavaScript to begin with, to check it is not failing at that point. If you simply put an alert message when the ‘ready’ state changes, you can know at least it is getting that far and can then debug your own code.

We will try and help where we can but can’t assist with debugging your custom solutions. If you send the URL on which you are trying to use the API in a support ticket, we will do our best to advise.

Receiving events from the HTML5 player

Using the HTML5 postMessage feature the Buto HTML5 player will send the following events to your application:

  • buto-loadstart at the load of the player
  • buto-play when the play button is first clicked
  • buto-ended when the video has ended

In your application you can then add event handlers for these events and trigger suitable events on the page.
For example:


window.addEventListener('message', function(event){ 
    if (event.data=='buto-ended'){ // is the event fired a video ended event?
        alert('video has ended'); // your function goes here
    } 
},false);

This functionality is only avaliable in IE9 and above when using the HTML5 (non-Flash player).

I would like to write my own library

Simply visit https://embed.buto.tv/javascript-player-api in your browser and you will be given the latest version of the library. Edit the end of the file name, replacing .min.js with simply .js. This will serve the original version of the library, with all whitespace in, so you should be able to easily see how it works. We can’t assist with your own implementation however.