Embedding the WebTvPlayer (v1)

Welcome! This documentation will guide you to embedding the WebTvPlayer in your website.

Features

The WebTvPlayer provides the same functionalities you would expect from any other video player.

• A rich JavaScript API;
• Adjustable playback speed;
• Buffering and progress report;
• HLS and MPEG-DASH streaming with auto-adaptive and on-demand video resolution selection;
• Customizable UI with vector SVG graphics.

Skins

The WebTvPlayer offers different skins which can be selected with a specific configuration option. If you want to customize one of our skins, please take a look at the overrides section, otherwise you can build your own skin from scratch as explained in the custom skins section.

See how the player looks with the skin WebTvPlayerDefaultSkinnull (chromeless)

The chromeless skin has no options.

Table of contents

1. Getting started
2. Configuration options
3. Secure playback
4. Tracking progress
5. Properties
6. Methods
7. Events
8. Overrides
9. Custom skins
10. Samples
11. Playground

Getting started

First, you'll need a free API Key from the Halleymedia staff, so contact us at dev@halleymedia.com.

After you got your API Key, initializing the WebTvPlayer user interface in your website is super easy. We provide two different initialization options to suit your needs.

Initialization option #1: using the JavaScript SDK

By using our JavaScript SDK, you can inject the WebTvPlayer user interface right into a container element, such as a div located in your HTML page. The container element can be sized to your liking, since the WebTvPlayer has a responsive layout. However, if the element has no defined height, the WebTvPlayer will adjust it as necessary.

Add this initialization code right before the closing of the body tag. The container element can be placed anywhere on your page.

<div id="player-container" style="width: 640px; height: 360px;"></div>
<script src="https://video.cirfood.com/v1/embed/webtvplayer.js?apiKey=YOUR_API_KEY"></script>
<script>
  var playerContainer = document.getElementById("player-container");
  var videoId = 1;
  var webTvPlayer = new WebTvPlayer(playerContainer, videoId);
</script>

Or, if you're using jQuery, you might prefer a more concise syntax.

<div id="player-container" style="width: 640px; height: 360px;"></div>
<script src="https://video.cirfood.com/v1/embed/webtvplayer.js?apiKey=YOUR_API_KEY"></script>
<script>
var videoId = 1;
var webTvPlayer = $("#player-container").webTvPlayer(videoId);
</script>

In both these examples, an object of type WebTvPlayer is returned. Subscribe to the ready event and then you'll be able interact with its public API that's documented in the properties and methods sections. Here's an example.

webTvPlayer.on('ready', function() {
    //Here it's safe to use the WebTvPlayer public API, e.g.:
    this.speed = 1.5;
    this.volume = 0.8;
});

Initialization option #2: using an iframe tag

This option is expecially needed when executing JavaScript is not allowed for some reason. Just add this iframe element anywhere in the page. Set a proper width and height for the iframe tag.

<iframe src="https://video.cirfood.com/v1/embed/webtvplayer.html?apiKey=YOUR_API_KEY&videoId=videoId" style="width: 640px; height: 360px; border: 0"></iframe>

What to do next?

The WebTvPlayer provides plenty of customization for both initialization options. Jump to the configuration and samples sections for more in-depth customization examples. For a deeper level of customization, take a look at the overrides section.

If you want to protect your video content from anonymous access, read how to properly initialize the WebTvPlayer in the secure playback section.

Configuration options

When initializing the WebTvPlayer you can provide some configuration options to control its final appearance.

If using the JavaScript SDK, provide a configuration object as an additional argument to the initialization method, like in this sample.

<script>
var playerOptions = {
    skin: null,
    segment: 4.0
};
//Using the global function
var webTvPlayer1 = new WebTvPlayer(playerContainer1, videoIdOrJwt, playerOptions);
//Or, using jQuery
var webTvPlayer2 = $(selector).webTvPlayer(videoIdOrJwt, playerOptions);
</script>

Instead, if you're using the iframe, you can pass configuration options as query string parameters.

<iframe src="https://video.cirfood.com/v1/embed/webtvplayer.html?apiKey=YOUR_API_KEY&videoId=videoId&skin=skinName&segment=4.0" style="width: 640px; height: 360px; border: 0"></iframe>

All available options are listed in the following paragraph.

Option list

Skin-specific configuration options for WebTvPlayerDefaultSkin

Secure playback

If you want to protect content that's only available to paying users, then you need to prevent anonymous access. The WebTvPlayer won't play protected videos if you just provide their ID: instead, you should provide a signed JSON Web Token (JWT) like in the following example:

var jwt = "eyJhbGciOiJIUzI1..."; //JSON Web Token, generated server-side
var webTvPlayer = $("#player-container").webTvPlayer(jwt);

You should generate a JWT with a payload containing the following claims:

• iss: the issuer (e.g. the URL of your web application, such as https://example.org);
• sub: the ID of the requested video;
• exp: a GMT date of expiration (e.g. 1 hour in the future). The video won't be playable after this date has expired. The value should be expressed as a unix timestamp (i.e. number of seconds elapsed since 1970/01/01 00:00:00 GMT);
• name: an opaque identifier of the user (e.g. the user ID or a hashed value) which will be used to track and identify abnormal behaviors.

Here's an example of a valid payload.

{
  "iss": "https://example.org",
  "sub": "1",
  "exp": 1516239022,
  "name": "3415"
}

You should then sign this payload on the server-side of your application using the HS256 algorithm. The secret key used to sign the payload must be shared with the Halleymedia staff. Contact us via e-mail at dev@halleymedia.com.

The WebTvPlayer will then securely load the video by using Pre-Signed Cookies with the provided expiration, thus granting access for a limited time and exclusively from the IP address of the user. This security mechanism severly discourages any attempt of unauthorized access by malicious users.

Tracking progress

Tracking individual segments

If you're using the JavaScript SDK, then you can track a user's progress on the current video. Just subscribe to the progress event to be notified each time the user has watched a short segment of the video.

webTvPlayer.on('progress', function(index, start, end, percentage) {
    console.log("The user has watched the segment with index " + index + " starting at " + start + "s and ending at " + end + "s. He watched " + Math.round(percentage) + "% of the video.");
    //TODO: send an ajax request to your backend in order to save the user progress, or just push an event to Google Tag Manager dataLayer.
});

Each segment has a default duration of 5 seconds, so the progress event will trigger every 5 seconds. You can change the segment duration by providing a segment property in the configuration options. Here's a comple example.

<div id="player-container" style="width: 640px; height: 360px;"></div>
<script>
var videoId = 1;
var playerOptions = {
    segment: 1.0 //Each segment will have a duration of 1 second
};
var playerContainer = document.getElementById("player-container");
var webTvPlayer = new WebTvPlayer(playerContainer, videoId, playerOptions);
webTvPlayer.on('progress', function(index, start, end) {
    //This will now trigger every second, as long as the video is playing
    console.log("The user has watched the segment with index " + index + " starting at " + start + "s and ending at " + end + "s.");
});

Tracking percentage

If you're just interested in tracking a percentage value, you could subscribe the percentage event instead which will fire only for interger values.

webTvPlayer.on('percentage', function(percentage) {
    console.log("The user has watched " + percentage + "% of the video."); //percentage being an integer value
    //TODO: send an ajax request to your backend in order to save the user progress, or just push an event to Google Tag Manager dataLayer.
});

Tracking with Google Tag Manager

If you wish to use a purely unobtrusive tracking solution, you can rely on Google Tag Manager instead of subscribing the progress or percentage events in the page.

Create a new Custom JavaScript Variable and write code which will do the following:

• Listen to the webtvplayer.create DOM Event in order to be notified of newly created instances, or iterate through the WebTvPlayer.instances property;
• Subscribe the progress, percentage or any of the other events of the WebTvPlayer;
• Push an event to window.dataLayer;
• Reference the Custom JavaScript Variable from some trigger, or it won't be activated in Normal Mode.

We prepared a ready-made recipe you can import into your Google Tag Manager Container. All pushed events will be relayed to Google Analytics so just be sure to amend the Google Analytics Settings Variable with your Account ID.

Properties

When a WebTvPlayer is initialized with the JavaScript API, an object of type WebTvPlayer is returned. Here's a list of its public properties.

Player-related properties

These properties can be used after the ready event has occurred.

Video-related properties

These properties can be used after the load event has occurred.

Constructor properties

These areproperties that are available right away on the WebTvPlayer constructor function.

Methods

When a WebTvPlayer is initialized with the JavaScript API, an object of type WebTvPlayer is returned. Here's a list of its public methods.

Player-related methods

These methods can be used after the ready event has occurred.

Video-related methods

These methods can be used after the load event has occurred.

Events

The WebTvPlayer object can raise a few events. Subscribe them by name, using the on method.

webTvPlayer.on('eventName', function() { /* your code here */ });

Conversely, you can stop being notified by invoking the off method. The callback argument is optional: if it's not provided, all subscribed callbacks are removed for that event.

webTvPlayer.off('eventName');

When a callback is invoked, the this keyword references the current instance of WebTvPlayer.

Instance events

DOM Events

Overrides

When you want to make small changes to the behavior or the appearance of the WebTvPlayer beyond what's allowed by configuration options, you provide overrides. Basically, an override is a javascript function which will replace or add your custom logic to the original function. Suppose you want to change just the play button icon of the default skin: you override the getSkinResource function to do so.

var playerContainer = document.getElementById('player-container');
var videoId = 1;
var playerOptions = {
  overrides: {
    getSkinResource: function(originalFunction, resourceName) {
      switch(resourceName) {
        //We want to replace just the play button, so let's return our own url in this case
        case "play":
          return "https://example.com/images/my-own-play-icon.svg";
    
        //In all other cases, let's invoke the original function to return its result untouched
        default: 
          return originalFunction(resourceName);
      }
    }
};
var webTvPlayer = new WebTvPlayer(playerContainer, videoId, playerOptions);

Of course, if you wanted to perform more important changes, you might as well code your own custom skin.

Main override list

Skin-specific override list for WebTvPlayerDefaultSkin

Custom skins

The WebTvPlayer keeps its logic separated from the UI, so you can provide a completely custom skin, if you want. Creating a custom skin is an advanced task so, before actually embarking on this journey, think if the desired result might be achieved simply by providing overrides or by defining CSS rules.

If you're determined in creating your own skin, then use the code of the WebTvPlayerDefaultSkin as a reference.

At minimum, you'll have to create an object constructor exposing a render function, which the WebTvPlayer will invoke. We suggest using the Object.defineProperty to make it read-only.

function MySkin()
{
    function render() {
        var playerInstance = this; //The this keyword references the WebTvPlayer instance
        //You can use the WebTvPlayer instance to access its public API
        //Here we get the containing element and change its style...
        playerInstance.container.style.border = "2px solid red";
        //...then we append a play button to it
        var button = document.createElement('button');
        button.setAttribute('type', 'button');
        button.innerText = 'Play';
        button.addEventListener('click', function() { playerInstance.play(); }, false);
        playerInstance.container.appendChild(button);
    }
    //Let's expose the render function
    Object.defineProperty(this, 'render', {
        get: function() { return render; },
        configurable: false
    });
}

Inside your skin constructor you can, of course, organize the code as your prefer. In this example, the play button was added inside the render function but you're absolutely free (and encouraged) to create smaller methods to improve code readability.

When you're done, pass a reference to the constructor to the skin property of the configuration object.

var playerContainer = document.getElementById('player-container');
var videoId = 1;
var playerOptions = {
  skin: MySkin //pass a reference to the constructor, not to a constructed object
};
var webTvPlayer = new WebTvPlayer(playerContainer, videoId, playerOptions);

Samples

Here's a brief gallery of code samples.

TODO

Playground

TODO