The Session API

Session API Overview

The session API allows the application layer to communicate with the Universal Session Manager (USM) to retrieve information about the current session as well as other components actively attached to the current session. The Session API consists of three web services installed on the platform:

  • http://session/: to obtain session and client properties
  • http://session/client: to communicate with the client device
  • http://session/management: to manage the session itself 

The following subsections describe the options and usage of these web services.

Direct Usage

The Session API uses the standard XMLHttpRequest object as its interface between the application and the session manager. It is highly preferred (and in the case of polling for messages -  required ) that the connection between the application and the USM be asynchronous. By using the XMLHttpRequest object it is easier for developers to avoid proprietary code when developing an application that might run on ActiveVideo CloudTV as well as another platform.

How to send/receive passthrough messages

To send a message, use the POST method and send it from your app to POST http://session/client/send?protocolid=:protocolid

  1. Note: When deciding what to post, the target deployment (cable, over the top, mobile device, etc.) plays a role in whether UTF-8/16 or binary strings should be sent. If you are sending messages directly to the device, please request further information from the operator regarding the format of the message strings.
    var CONTENT = "this is a message";var x = new XMLHttpRequest("POST","http://session/client/send?protocolid=0",true);
  2. Here, :CONTENT is the body of the HTTP request. This is used in the application to send the :CONTENT to the client device, together with a :protocolid, indicating the protocol used.
  3. CloudTV H5 simply passes the content and the protocol identifier to the client device. The :protocolid and :CONTENT can be anything, as long as they are meaningful to the client device. Contact ActiveVideo and coordinate with the Operator on details of client devices and meaningful content before using this API.
  4. IMPORTANT: when developing in your browser, you will see 404 messages because the domain http://session only exists within a CloudTV deployment.

How to receive messages

To listen for messages, long poll the session manager on http://session/client/poll.

TIP: Only one connection to http://session/client/poll is allowed per device session. The connection will be held by the Stitcher until a message is received for the application. This means that if no communication is encountered, a single connection MAY PERSIST AN ENTIRE SESSION. This is by design, and you should not close the connection unless you receive a response (readyState == 4).

window.listen = function(){
    var x = new XMLHttpRequest("GET","http://session/client/poll",true);
    x.onreadystatechange = function(){
        if(this.readyState == 4){
            console.log("received message: " + this.responseText);
            window.listen(); //Make sure to restart this function
    x.send("this is a message");
window.listen();//start listening

How to manage the inactivity timer

An inactivity timer is considered a counter that runs above the navigator level, at the actual connection point between the device and CloudTV, that keeps track of user key presses. If a user is inactive for a configurable amount of time, a session can be terminated (much like a screen saver, except the task of resuming the session upon user return is determined by the application).

  1. To reset the inactivity timeout:
    GET http://session/management/reset-timeout
  2. Or to reset the timeout and assign a new value (in seconds) to it:
  3. To exit a session:
    Use  _window.close()_  on all windows within your application, or
    [GET] http://session/management/exit>

Session Features


  1. http://session/client/tuners
    • This returns a list of tuner identifiers of the tuners in the client device. Currently, it always returns [{"id" : 1}].
  2. http://session/client/tuners/:tunerid?channel=:channel
    • This tunes the tuner :tunderid to :channel

Client Properties


This returns the capabilities of the client device. This is an example of a result:

    "avcdcConfigHD": "1",
    "abps": "128",
    "audioCodec": "ac3",
    "initialIFrames": "1",
    "bitrateMode": "vbr",
    "TSProgramPID": "64",
    "TSProgramID": "1",
    "TSPcrPID": "67",
    "display": "hd1080",
    "lang": "en",
    "sessionTsPsiInterval": "1",
    "TSVideoPID": "65",
    "transport": "http",
    "clientIDPattern": "^avplay.*",
    "deviceClass": "StandardDevelopmentHTTPClient",
    "achannels": "2",
    "avcdcConfigSD": "0",
    "videoCodec": "h264",
    "TSAudioPID": "66",
    "TSLogPID": "68"

Time-Out Management

User sessions have an inactivity timer. By default, this is set to two hours. Each user key press resets the inactivity timer. For applications with little user interaction, it is possible to reset this timer:


This restarts the inactivity timer with a new time-out value of :timeout.

Session Exit


This terminates the session that the application is running in.

CAUTION: Terminating a user session is a radical action. A more normal use case is, when an application closes, the client should switch back to the previously active application. For this purpose, use window.close. Only use the session exit API in the specific case an application should terminate the full session.  In that case, first consult with ActiveVideo.

Session Properties


This returns the properties of the session and the client device, for example, the session id and client id. This is an example of a result:

    "res": "1920x1088",
    "secureid": "d0e7fcee-2994-41dd-a666-15eef8c18aeb",
    "sUtc": "1354633277143",
    "sessionID": "937033c8-cdcc-4735-bc0d-833a7a52a456",
    "clientID": "avplay-14:10:9F:D0:09:4B",
    "sessionType": "0",
    "display": "hd1080"
  • Monday, 17 December 2012

Your destination to find out more about just how easy it is to develop advanced applications that leverage the “write-once, deploy-everywhere” content creation environment of ActiveVideo’s CloudTV™ platform. You will be able to significantly reduce app time-to-market for connected devices of all types, as well as cable settop boxes that have no additional connectivity. Manufacturers and virtual service providers, as well as cable and IPTV operators around the world are currently benefiting from the advantages of ActiveVideo’s CloudTV platform.

© 2019 Active Video Networks. All Rights Reserved