Presentation API polyfill

The polyfill is not intended for use in production. It explores various discovery and launch mechanisms that the Presentation API could be built upon, with a view to providing concrete feedback on the specification to the Second Screen Working Group.

The polyfill explores discovery-based mechanisms (the controlling device discovers and controls the second device) and invitation-based mechanisms (the controlling device invites nearby devices to launch a URL). Presentation mechanisms that are currently supported are:

Important: The establishment of a communication channel between the peers is either not fully implemented (Cast, Window) or simply not available at all when it cannot be established automatically (DIAL, HbbTV, QR Code). The polyfill uses an isChannelOptional presentation request option flag to let the calling app specify whether it needs a communication channel (the default) or will handle the communication on its own. Advanced features such as reconnection to running presentations or even terminating a presentation is not supported either. The polyfill will be improved over time.

Usage

NB: The polyfill uses a w3c prefix to avoid collisions with native implementations of the Presentation API.

The Presentation API polyfill is a standalone JavaScript file, available at:
https://mediascape.github.io/presentation-api-polyfill/API/presentation-api-polyfill.js

Additional dependencies need to be included to enable some of the presentation mechanisms supported by the polyfill.

Controlling code

On the controlling side, the Presentation API polyfill must be included together with the Cast sender library to support the Cast presentation mechanism and the QRCode.js library for the QR code presentation mechanism. The application may then create a w3cPresentationRequest instance and call start() on that instance to effectively start the presentation and try to establish a communication channel with the receiving side.

<script src="https://davidshimjs.github.io/qrcodejs/qrcode.min.js"></script>
<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js"></script>
<script src="https://mediascape.github.io/presentation-api-polyfill/API/presentation-api-polyfill.js"></script>
<script type="text/javascript">
  // Start new session.
  var request = new w3cPresentationRequest(
    'http://mediascapeproject.eu/', { isChannelOptional: true });
  request
    .start()
    .then(function (connection) {
      connection.onstatechange = function () {
        if (connection.state === 'connected') {
          console.log('data channel is available');
          connection.send('hello receiving side!');
        }
        else if (connection.state === 'closed') {
          console.log('data channel is closed, presentation may still be running');
        }
        else {
          console.log('presentation terminated');
        }
      };
      connection.onmessage = function (event) {
        console.log('received message from receiving side', event.data);
      };
    })
    .catch(function (error) {
      console.log('could not create presentation', error);
    });
</script>

Mechanisms that cannot be fully implemented within the Web runtime make use of a local Node.js backends to accomplish the tasks that they cannot achieve on their own. To launch these backends, first fetch the required code:

git clone https://github.com/mediascape/presentation-api-polyfill.git
cd presentation-api-polyfill
npm install

Then run each backend server in its own command-line window. To enable the Physical Web mechanism, run:

node Server/ble-beacon.js

To enable the DIAL and HbbTV 2.0 mechanisms, run:

node Server/dial-proxy.js

Receiving code

On the receiving side, the Presentation API polyfill must be included together with the Cast receiver library to support the Cast presentation mechanism, although note that the polyfill is useless when invitation-based mechanisms are used (such mechanisms do not know anything about the receiving so cannot connect with them). The receiving application may then monitor incoming presentation connections to be able to exchange messages with the controlling side.

<script src="https://www.gstatic.com/cast/sdk/libs/receiver/2.0.0/cast_receiver.js"></script>
<script src="https://mediascape.github.io/presentation-api-polyfill/API/presentation-api-polyfill.js"></script>
<script type="text/javascript">
  navigator.w3cPresentation.receiver.getSession().then(function (connection) {
    connection.onstatechange = function () {
      if (connection.state === 'connected') {
        connection.send('hello controlling side!');
      }
      else if (connection.state === 'closed') {
        console.log('data channel is closed');
      }
      else {
        console.log('controlling side terminated the presentation');
      }
    };
    connection.onmessage = function (event) {
      console.log('received message from controlling side', event.data);
    };
  });
</script>

Implementation details

The source code of the Presentation API polyfill is available on GitHub under a W3C Software and Document License.

The Presentation API JS polyfill closely follows the interfaces and algorithms defined in the latest draft of the Presentation API specification. On top of these interfaces, the Presentation API polyfill exposes a small set of interfaces that may be used to implement new presentation mechanisms. These classes are exposed in the navigator.w3cPresentation.extend namespace. They are:

log: Short helper function to log things to the console.
_DOMException: Custom implementation of DOMException (pending support from browser vendors)
DataChannel: Represents a communication channel that exposes a send() method and message events.
RemoteController: Represents a remote controller as seen by the receiving application. This interface mostly only exposes a createDataChannel() method that the Presentation API polyfill running on the receiving side uses to establish the communication channel.
Display: Represents a display that is available for presentation. In fact, in the polyfill, classes of displays are also represented as a display. A display can be navigated to a specific URL thanks to the navigate() method it must implement.
PresentationMechanism: Main class that additional presentation mechanisms must implement. The getAvailableDisplays() method returns the promise to get a list of available displays. The monitorIncomingControllers() method starts the monitoring of incoming controllers on the receiving side.
registerPresentationMechanism(): The method that presentation mechanism must call with a PresentationMechanism instance to register themselves with the polyfill.

Presentation API polyfill

Examples

Usage

Controlling code

Receiving code

Implementation details

Contact

Acknowledgements