Private Videos With Custom Players Session Retention

There are quite a few cases where you would want to include other assets in the session where you play your video. In example:

  • Displaying a clickable thumbnail that redirects to your video
  • Selection of multiple players with a fallback (hls to mp4 fallback)
  • Using a custom built player

In these cases, you will have to make multiple requests to api.video assets. As it's a secured session we are using a Session Token in order to retrain the session and make sure it's continuous.

What is a Session Token?

In short a Session Token is api.video's way of retaining the session for every request you make to each asset. You can find the detailed article about session tokens here.

Example for incorrect usage of private videos

Let's take an example where you want to create a clickable thumbnail which will lead to the video. If we just write the following HTML it will not work, you will get a 404 error:

<html>
  <head>
  </head>
  <body>
    <a href=\"https://vod.api.video/vod/{video id}/token/{private token}/mp4/source.mp4\">
      <img src=\"https://vod.api.video/vod/{video id}/token/{private token}/thumbnail.jpg\" height=\"30%\" width=\"30%\">
    </a>
  </body>
</html>

How to play private video in a custom built player?

In order to play your private video with a clickable thumbnail or in a custom made player, you will first have to call the session token. Assuming that you are passing an .mp4 video to the player, the flow will be as follows described in the Session Flow document.

Continuous requests while playing private videos on custom player

In some cases you would need to make further requests to get different assets for the video, for example other qualities or different assets (hls or mp4), while retaining the same session. We've made sure that this task is easy as possible for you by using the session token.

Examples

Let look at some cases where we can build an application that will use the Session Token when delivering a private video

Node.js example: Delivering the video with video.js and adding a thumbnail on the top

You can find the source for the example below on GitHub.

Check out an example of consuming private videos and thumbnail with video.js (Node) below.

  • We first build a wrapper that will make requests to the api.video API, while passing it a hardcoded API key in order to reuse that function in the future.

  • With the use of the wrapper we then make a request to the /videos endpoint to get the video by id. That function will return the mp4 url of the video from the response.

  • We need that url in order to extract the private token from it, the private token is needed in order make the request to the /session endpoint and get the session token.

  • With a regex function, we will extract the private token from the url in the response

  • Now that we have the private token, we make a request to the /session endpoint

GET https://vod.api.video/vod/{videoId}/token/{private token}/session
  • We will get a response with the session token in JSON format.
{"session_token": "111-222-333"}
  • We will use the session token and include it as a query string in the GET request to the next asset that we request from the API, in our case it's the thumbnail
GET https://vod.api.video/vod/viXXX/token/AAA-BBB-CCC/thumbnail.jpg?avh=111-222-333
  • Finally, our server will generate an HTML response to the client.

You can find the complete code below:

const http = require('http');
const url = require('url');
const base64 = require('base-64');

const vodUrl = 'https://vod.api.video/vod/';
const wsUrl = 'https://ws.api.video/videos/';
//const sample video id = 'xxxxxxxxxxxxxxx';
const apiKey = 'Your API Key';

/************************************************************************
 *  This is an example of how you can handle private videos with the
 *  use of session tokens. In the example we will create an HTTP server
 *  that will handle incoming GET requests, with the video id in the 
 *  query string. Then it will make a request to get the video id from 
 *  the https://ws.api.video/videos/ endpoint, extract the private token
 *  , get the session token from the /session endpoint and finally consume
 *  the video and thumbnail.
 * ***********************************************************************/

// 1 - First create a server that will accept GET requests, with id as query parameter

const server = http.createServer( async (req, res) =>  {
    const videoIdFromReq = url.parse(req.url, true).query.id;
    const videoDetails = await getVideoDetailsById(videoIdFromReq);
    const privateToken = await videoDetails.extractPrivateTokenAssets();
    const sessionToken = await videoDetails.getSessionToken(privateToken);
    const html = await generateHTML(videoDetails.data, sessionToken);
    res.write(html);
});

server.listen(3000);
console.log('Node.js web server at port 3000 is running..')

// 2 - Create a handler function for the requests to api.video endpoints with the basic auth
const apiVideoReq = async (url) => {
    const headers = new Headers();
    headers.append('Authorization', 'Basic' + base64.encode(apiKey + ":"));
    const response = await fetch(url, {headers});
    return {
        httpRawResponse: response,
        processHTTPresponse: async () => {
            if(response.status === 200) {
                const data = await response.json();
                return data;
            } else {
                throw new Error(`unbale to prase JSON, got response status: ${response.status}`)
            }
        }
    }
}

// 3 - Create a function to get the video by id reusing the above functions
const getVideoDetailsById = async (videoId) => {
    const completeUrlWithVideoId = `${wsUrl}${videoId}`
    const apiResponse = await apiVideoReq(completeUrlWithVideoId);
    const videoDetails = await apiResponse.processHTTPresponse();
    return {
        data: videoDetails,
        // 4 - extract the private token from the assets response
        extractPrivateTokenAssets: async () => {
            const regexBtwnTokenMp4 = /(?<=token\/)(.*?)(?=\/mp4)/;
            const regexMatchResults = videoDetails.assets.mp4.match(regexBtwnTokenMp4);
            if(regexMatchResults.length > 0) {
                return regexMatchResults[0]
            } else {
                throw new Error(`Was not able to find the private token the asset url: ${assetUrl}`)
            }
        },
        // 5 - get the session token while passing the private token
        getSessionToken: async (privateToken) => {
            const sessionUrlWithVideoIdAndToken = `${vodUrl}${videoId}/token/${privateToken}/session`
            const res = await apiVideoReq(sessionUrlWithVideoIdAndToken);
            const data = await res.processHTTPresponse(res);
            return data.session_token;   
        }
    }
}

// 6 - generate the HTML with video.js, the mp4 url and the thumbnail, while passing in the session token
const generateHTML = async (data, sessionToken) => {

    if(data.assets && data.assets.mp4 && data.assets.thumbnail) {
        const mp4Url = data.assets.mp4;
        const thumbnailUrl = data.assets.thumbnail;
        return `<html>
        <head>
        <div style="max-width: 150px" >
        <img
        style="max-width:100%;" 
        src="${thumbnailUrl}?avh=${sessionToken}">
        </div>
        </head>
        <body><video
        controls
        preload="auto"
        width="640"
        height="264"
        data-setup="{}"><source src="${mp4Url}?avh=${sessionToken}" type="video/mp4" /></body></html>`
    }
}

Was this page helpful?

On this page