HTML5 Second Screen SDK

The HTML5-based Red5 Pro Second Screen SDK utilizes Websockets for communication with support for a Flash fallback for unsupported browsers.

Download the Red5 Pro HTML5 Host Second Screen SDKs Download the latest
Host and Client Scheme SDKs for HTML5

The SDK contains support for the following second screen elements:


Prerequisite

In order to run an HTML5 Second Screen application, you must already have a Native Client installed on your favorite device with support for Red5 Pro Second Screen.

In order to fulfill this requirement, you can build the examples we have provided:

Download the Red5 Pro iOS Native Client Download the latest
iOS Native Client Example
Visit the Red5 Pro Android Second Screen Quickstart Download the latest
Android Native Client Example

Additionally, you can follow along with the provided Quickstarts to build your own Native Clients:

Visit the Red5 Pro iOS Second Screen Quickstart Visit the Second Screen
iOS Native Client Quickstart
Visit the Red5 Pro Android Second Screen Quickstart Visit the Second Screen
Android Native Client Quickstart

Quickstart Overview

We will be using both the HTML Host and Client libraries in order to demonstrate bi-directional communication between the Host and Client applications.


HTML Host Library

The HTML5 Host Library allows for managing Client connection and communication to and from any number of Clients. The following is a quick preview of the functionality that the Host Library provides:

Install & Access Host

<!doctype html>
<html>
  <head>
    <script src="lib/secondscreen-host.min.js"></script>
  </head>
  <body>
    <ul id="device-list"></ul>
    <script>

      var r5proHost = window.secondscreenHost.noConflict();

    </script>
  </body>
</html>

The Host is installed in a non-conflicting manner on the off chance that secondscreenHost is already residing on the window global.

It is recommended to install the host in the <head> in a blocking manner so as to be able to readily access it at any later point. The following sizes of the Host SDK Library:

Unminized Minimized Compressed
124KB 61KB 17.38KB

Start Host

var r5proHost = window.secondscreenHost.noConflict();

r5proHost.start({
  name: 'Second Screen Host Example',
  registryAddress: "REGISTRY_ADDRESS_HERE",
  controlMode: host.ControlModes.HTML,
  controlsUrl: "scheme/client.html",
});

Calling start() will connect the Host to the registry to be recognized by any Client who registers as well. The user-facing Client application is defined using the controlMode and controlsUrl configuration properties and will be delivered to each Client who opts to connect to this Host.

Registering Host

The host registers for availability on the registry server that is available through the Red5 Pro Second Screen Plugin. Replace REGISTRY_HOSTNAME_HERE with the IP location of the Red5 Server that is utilizing the Second Screen plugin.

Monitor Client Connection

var r5proHost = window.secondscreenHost.noConflict();

r5proHost.start({
  name: 'Second Screen Host Example',
  registryAddress: "REGISTRY_ADDRESS_HERE",
  controlMode: host.ControlModes.HTML,
  controlsUrl: "scheme/client.html",
});

r5proHost.on(r5proHost.EventTypes.DEVICE_CONNECTED, function(e) {
  var li = document.createElement('li');
  var label = document.createTextNode(e.device.name);
  li.id = e.device.id;
  li.appendChild(label);
  document.getElementById('device-list').appendChild(li);
});

r5proHost.on(r5proHost.EventTypes.DEVICE_DISCONNECTED, function(e) {
  var deviceEntry = document.getElementById(e.device.id);
  document.getElementById('device-list').removeChild(deviceEntry);
});

The Host is notified of Client connection status through its EventTypes enumeration. There are several other events related to the Host and Client connections that are discussed in more detail found at the literal documentation for the Host SDK Library.

Send To Clients

<!doctype html>
<html>
  <head>
    <script src="lib/secondscreen-host.min.js"></script>
  </head>
  <body>
    <form>
      <label for="messageField">Send Message:</label>
      <input name="messageField" id="messageField" value="hello from host!">
      <button id="sendMessageButton" type="button">GO!</button>
    </form>
    <script>

      var r5proHost = window.secondscreenHost.noConflict();

      r5proHost.start({
        name: 'Second Screen Host Example',
        registryAddress: "REGISTRY_ADDRESS_HERE",
        appId: "second screen",
        controlMode: host.ControlModes.HTML,
        controlsUrl: "scheme/client.html",
      });

      r5proHost.on(r5proHost.EventTypes.DEVICE_CONNECTED, function(e) {
        e.device.send('custom-event', {
          message: 'hello, you are device ' + r5proHost.devices.length + ' in the group.'
        });
      });

      document.getElementById('sendMessageButton').on('click', function() {
        var message = document.getElementById('messageField').value;
        r5proHost.allDevices().send('custom-event', {
          message: message
        });
      });

    </script>
  </body>
</html>

The Host can dispatch data events to a single Client through send(). The signature for send:

Name Type Description
type String The type of message to send and to access on the Client
...args List of optional arguments You can pass any number of data, like any RPC messaging, but we recommend sending two params: a state string and an object representing that state.

The type is non-restrictive nor enumerated on the Host — it can be whatever String value the Host wants to use and recognized by Clients.

In this example the device instance is accessed from the event object on DEVICE_CONNECTED. A map of all connected devices is available through r5proHost.devices.

Additionally, the Host can dispatch data events to all connected Clients through the allDevices() collection proxy API.

Receive From Client

<!doctype html>
<html>
  <head>
    <script src="lib/secondscreen-host.min.js"></script>
  </head>
  <body>
    <ul id="message-list"></ul>
    <script>

      var r5proHost = window.secondscreenHost.noConflict();

      r5proHost.start({
        name: 'Second Screen Host Example',
        registryAddress: "REGISTRY_ADDRESS_HERE",
        controlMode: host.ControlModes.HTML,
        controlsUrl: "scheme/client.html",
      });

      r5proHost.on(r5proHost.EventTypes.MESSAGE, function(e) {
        var device = e.device;
        var message = e.message;
        var state = e.state;
        var li = document.createElement('li');
        var label = document.createTextNode([device.name, message, JSON.stringify(state,null,2)].join(' : '));
        li.appendChild(label);
        document.getElementById('message-list').appendChild(li);
      });

    </script>
  </body>
</html>

All messages received from Clients is captured in the MESSAGE event on the Host. On the event object is:

Property Description
message The message type
device Reference to the issuing Client
state The JSON data sent from the Client

Stop Host

var r5proHost = window.secondscreenHost.noConflict();

r5proHost.start({
  name: 'Second Screen Host Example',
  registryAddress: "REGISTRY_ADDRESS_HERE",
  controlMode: host.ControlModes.HTML,
  controlsUrl: "scheme/client.html",
});

r5proHost.stop();

Calling stop() will shut down all connections and remove the Host from the registry.

Additional Host Documentation

API Documentation

For a java-doc style API overview, please refer to HTML Host Second Screen API Documentation


HTML Client Library

The Second Screen Client is an application that resides on your device. It has the ability to communicate with a Second Screen Host using the respective SDKs as well as loading a custom web page. The HTML5 Second Screen Client SDK library, provides an easy means of communicating with a Host application.

The following are examples of HTML application for the Client — informally called a control scheme — that would be sent from the Host upon connection of device.

Install & Access Client

<!doctype html>
<html>
  <head>
    <script src="lib/bm-inject.js"></script>
    <script src="lib/secondscreen-client.min.js"></script>
  </head>
  <body>
    <ul id="message-list"></ul>
    <script>

      var r5proClient = window.secondscreenClient.noConflict();

    </script>
  </body>
</html>

The Client is installed in a non-conflicting manner on the off chance that secondscreenClient is already residing on the window global.

It is recommended to install the host in the <head> in a blocking manner so as to be able to readily access it at any later point. The following sizes of the Client SDK Library:

Unminized Minimized Compressed
21KB 10KB 3.56KB

Receive From Host

<!doctype html>
<html>
  <head>
    <script src="lib/bm-inject.js"></script>
    <script src="lib/secondscreen-client.min.js"></script>
  </head>
  <body>
    <ul id="message-list"></ul>
    <script>

      var r5proClient = window.secondscreenClient.noConflict();

      r5proClient.on('custom-event', function(data) {
        var message = JSON.parse(data.message);
        var li = document.createElement('li');
        var label = document.createTextNode(message);
        li.appendChild(label);
        document.getElementById('message-list').appendChild(li);
      });

    </script>
  </body>
</html>

All messages received from a Host is captured by the custom message type sent by the Host. The arguments provided to the event delegate is list of data passed from the Host through Device:send().

Send To Host

<!doctype html>
<html>
  <head>
    <script src="lib/bm-inject.js"></script>
    <script src="lib/secondscreen-client.min.js"></script>
  </head>
  <body>
    <form>
      <label for="messageField">Send Message:</label>
      <input name="messageField" id="messageField" value="hello from client!">
      <button id="sendMessageButton" type="button">GO!</button>
    </form>
    <script>

      var r5proClient = window.secondscreenClient.noConflict();

      document.getElementById('sendMessageButton').on('click', function() {
        var message = document.getElementById('messageField').value;
        r5proClient.send('custom-event', {message:message});
      });

    </script>
  </body>
</html>

A Client can dispatch a data event to the connected Host using send(). The signature for send:

Name Type Description
type String The type of message to send and to access on the Host
...args List of optional arguments The data to send to the Host

The type is non-restrictive nor enumerated on the Client — it can be whatever String value the Client wants to use and recognized by Host.

The bm-inject library

In the previous Client examples, you will see that a script file, bm-inject.js, is being loaded in the head of the web-page prior to the secondscreen-client.min.js SDK library.

The included bm-inject.js file in the Client SDK Library is not the file that will be loaded by the WebView on a Device Client.

The inclusion of this script, however, is required in order for the Device Client to intercept the URL request and inject a library that is necessary for communication between the Host and Client applications.


API Documentation

For more in-depth documentation about the structure of the HTML5 Second Screen Host SDK, please visit: HTML Client Second Screen API Documentation