Introduction

THEOplayer makes a number of network requests and receives responses while playing content video, these requests and responses can be intercepted to make a new or modified request or respond with a new response. The network object thus allows easy access to handle the network in an efficient way.

This guide explains how you set-up THEOplayer to add and remove request/response interceptors. This document guides you through setting up a demo just like the one that's showcased in our Demo Zone

The following topics will be covered:

  1. Prerequirements
  2. Starting Template
  3. Adding and removing Request Interceptor
  4. Adding and removing Response Interceptor
  5. HTTP Errors

 

1. Prerequirements

This guide expects that you have a THEOplayer license. If you aren't using THEOplayer yet, you can start your free trial here. Be sure to have THEOplayer version 2.21.0 or higher.

 

2. Starting Template

The first thing you need is a valid THEOplayer set-up. If you have no experience with setting up our player, we have an excellent getting started guide.

To get THEOplayer to work, you only need to do three things:

  1. Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
  2. Add a container which can hold your video player with HTML.
  3. Create your player through JavaScript using our API.

A basic HTML page with a working THEOplayer could look like the following:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
<title>THEOplayer 2.X: Getting Started</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="stylesheet" type="text/css" href='/path/to/ui.css'>
</head>
<body>
<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>
<script type='text/javascript' src='/path/to/THEOplayer.js'></script> <!-- ads THEOplayer library --> <script>
var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
sources : [{
src : 'https://cdn.theoplayer.com/video/sintel/nosubs.m3u8',
type : 'application/x-mpegurl'
}]
}; </script>
</body>
</html>

 

The two snippets below are the references to the JS and CSS library.

<link rel="stylesheet" type="text/css" href='/path/to/ui.css'>
<script type='text/javascript' src='/path/to/THEOplayer.js'></script> 

 

The following snippet is your HTML container.

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

 

This snippet initializes your player, including an HLS source.

<script>
var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
sources : [{
src : 'https://cdn.theoplayer.com/video/sintel/nosubs.m3u8',
type : 'application/x-mpegurl'
}]
}; </script>

To fully master THEOplayer, be sure to read our documentation.

 

3. Adding and removing Request Interceptors

Starting from the basic template above, you need to add a RequestInterceptor on the network object's addRequestInterceptor method. By adding a request interceptor, the original request made by HTTP can be modified so that specific properties of the original request can be altered to contain the necessary information, before it is sent to the server.

 

A request interceptor can be defined as follows either with a redirect or a respondWith method. In order to add interceptors where a redirect method needs to be used, the request type must match the redirected request type.

var myRequestInterceptor = function(request) {
if (request.url.indexOf('m3u8') !== -1) {
request.redirect({
url : 'https://cdn.theoplayer.com/video/elephants-dream/448/chunklist_w370587926_b688000_vo_slen_t64TWFpbg==.m3u8',
method : 'GET',
headers : {
'Content-Type' : 'application/x-mpegurl'
}
});
}
};

The code sample above intercepts manifest requests made by the player and redirects them to the provided request URL. The redirect method accepts a RequestInit object as its argument.

 

If the properties of the given RequestInit object are missing, the API uses the properties values from the original request.  In order to add interceptors where a respondWith method needs to be used, the response type must match the request's response type.

var myRequestInterceptor = function(request) {
if (request.url.indexOf('m3u8') !== -1) {
request.respondWith({
body : '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
status : 200,
statusText : 'OK'
});
}
};

The code sample above intercepts manifest requests made by the player and responds with a manifest containing a single segment. The respondWith method accepts a ResponseInit object as its argument.

 

The above defined interceptors can be added to the player as follows:

player.network.addRequestInterceptor(myRequestInterceptor);

 

Interceptors can be removed in a similar manner as follows:

player.network.removeRequestInterceptor(myRequestInterceptor);

 

4. Adding and removing Response Interceptors

A ResponseInterceptor responds with the given response for the original request.

ResponseInterceptor can be added on the network object's addResponseInterceptor method. By adding a response interceptor, the original response can be modified so that specific properties of the original response can be altered to contain the necessary information, before the server responds.

A ResponseInterceptor can be defined as follows with the respondWith method.

var myResponseInterceptor = function(response) {
if (response.url.indexOf('m3u8') !== -1) {
response.respondWith({
body : '#EXTM3U\n#EXTINF:6,\nhttps://cdn.theoplayer.com/video/elephants-dream/448/media_w370587926_b688000_vo_slen_t64TWFpbg==_0.ts\n#EXT-X-ENDLIST',
status : 200,
statusText : 'OK'
});
}
};

The code sample above intercepts manifest responses received by the player and responds with a manifest containing a single segment. The respondWith method accepts a ResponseInit object as its argument.

 

The above defined interceptor can be added to the player as follows:

player.network.addResponseInterceptor(myResponseInterceptor);

 

Interceptors can be removed in a similar manner as follows:

player.network.removeResponseInterceptor(myResponseInterceptor);

 

5. HTTP Errors

If the status code is set to a code between 200-299, the player responds with a successful response, in any other cases the player will respond with an HTTP error.

If the player originally responded with an HTTP error, the interceptor can change the response to a successful response and vice versa.

 

6. Adding and Removing Event Listeners

The 'online' and 'offline' events can be added to the network as follows:

player.network.addEventListener('online', handleThisEvent());

 

Events can be removed in a similar manner as follows:

player.network.removeEventListener('online', handleThisEvent());