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.

  1. How to send/receive passthrough messages

    • To send a message, use the POST method and send it from your app to:
      POSThttp://session/client/send?protocolid=<protocolid> <CONTENT>
      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 x = new XMLHttpRequest("POST","http://session/client/send?protocolid=0",true); 
        x.send("this is a message"); 
        
      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.
  2. How to receive messages

      • To listen for messages, long poll the session manager on http://session/client/poll<a< a=""> href="http://session/client/poll%20." data-mce-href="http://session/client/poll">. 
      • Make sure to always reopen the polling connection so that, should a message come in from the client, you do not have too much latency in reacting.
    TIP
        : Only one connection to
    http://session/client/poll is
        allowed per device session. The connection will be held by the Universal Session Manager (USM) 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(){</ul></ul>
        <ul><ul>  var x = new XMLHttpRequest("GET","</ul></ul>http://session/client/poll<ul><ul>",true);</ul></ul>
        <ul><ul>  x.onreadystatechange = function(){</ul></ul>
        <ul><ul>   if(this.readyState == 4){ </ul></ul>
        <ul><ul>      console.log("received message: " + this.responseText);</ul></ul>
        <ul><ul>      window.listen(); //Make sure to restart this function</ul></ul>
        <ul><ul>  }</ul></ul>
        <ul><ul>  x.send("this is a message");</ul></ul>
        <ul><ul>} </ul></ul>
        <ul>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:
        GET http://session/management/reset-timeout?timeout=3600>
      3. To exit a session:
        Use window.close() on all windows within your application, or
        GET http://session/management/exit>

Using the Integrated "session" library within the AVN Framework

The session APIs are highly dependent upon which protocol is being used. In broad terms, because a CloudTV application runs in the "cloud", the device that is in front of the user must maintain a connection with CloudTV and send and receive messages. Provided your target deployment allows you to use the session API, you may find it more intuitive to simply include the session library and begin listening for messages without managing the connection polling and formatting.

How to send/receive messages:

Step 1: Include the libraries

  <script src="/scripts/avhtml/av.js"></script>
  <script src="/scripts/avhtml/session.js"></script>

Step 2: Call any method of the Session library

Send a message "string" to the client device:

av.session.sendMessage(string)

Begin listening for a message from the client:

av.session.addEventListener('message', function(evt){
      console.log("Received message: " + evt.data + " from client" )
});

Tune the device to a channel (no suspend):

av.session.tuneTuner(123);//channel 123

Full API documentation on the session/client and other libraries are available with the ActiveVideo JavaScript Framework section of this site.

Session Features

Tuning

Note: The interfaces in this subsection currently are not supported.

http://session/client/tuners

This returns a list of tuner identifiers of the tuners in the client device. Currently, it always returns [{"id" : 1}].

http://session/client/tuners/<tunerid>?channel=<channel>

This tunes the tuner <tunerid> to <channel>.

Client Properties

http://session/client/properties.json
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:

http://session/management/reset-timeout?timeout=<timeout>

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

Session Exit

http://session/management/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

http://session/properties.json

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.

© 2017 Active Video Networks. All Rights Reserved