Embedding the WebTvPlayer (v2)

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. 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. Custom skins (classic JS)
9. Custom skins (ES6+)
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://embed.civicam.it/v2/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://embed.civicam.it/v2/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://embed.civicam.it/v2/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.

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://embed.civicam.it/v2/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

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('volume', function(arg) { 
    //Your code here
    console.log("New volume value", arg.volume);
});

Or by the event-specific method:

webTvPlayer.onVolume(function(arg) {
    //Your code here
    console.log("New volume value", arg.volume);
});

Conversely, you can stop being notified by invoking the off method. The callback argument is optional: if it's not provided, all registered callbacks are removed for that event name.
Note: if you just pass the special event name all, then any previously registered callback is removed (it doesn't matter what the event name was).

webTvPlayer.off('buffer', myCallback); //Remove just this callback (if it was registered before for the buffer event)
webTvPlayer.off('volume'); //Remove all callbacks previously registered for the volume event
webTvPlayer.off('all'); //Remove any previously registered callback

Each event might provide an object parameter when invoking your callback which defines ore or more properties. Referer to the following paragraph for the specifics.

Instance events

DOM Events

Custom skins (ES6+)

You can create skins using ES6 syntax. In this case, you should add the type definitions package to your project to assist you in the development.

npm install @halleymedia/webtvplayer-types

import WebTvPlayer from '@halleymedia/webtvplayer-types';
import WebTvPlayerSkin from '@halleymedia/webtvplayer-types/skins/WebTvPlayerSkin';

/**
 * @implements {WebTvPlayerSkin}
 */
export default class MySkin {

    /**
     * @param {WebTvPlayer} playerInstance
     * @param {Object.} callbackFunction
     */
    render(playerInstance, callbackFunction) {

        const button = playerInstance.container.ownerDocument.createElement('button');
        button.setAttribute('type', 'button');
        button.innerText = 'Play';
        button.addEventListener('click', function() { playerInstance.play(); }, false);
        playerInstance.container.appendChild(button);

        //You should invoke the callbackFunction with a custom element which will be used as the video container
        callbackFunction({
            'player': playerInstance.container.ownerDocument.createElement('div')
        });
    }

    destroy() {
        //Cleanup here
    }
    
}

Samples

Here's a brief gallery of code samples.

TODO

Playground

TODO