Presentation API

Draft Report 12 November 2013

This Version:: http://webscreens.github.io/presentation-api/20131112/
Latest Editor's Draft: http://webscreens.github.io/presentation-api/
Participate:: Send feedback to the community group's mailing list public-webscreens@w3.org, or create or browse open issues on GitHub. Also, you may join on the CG's IRC channel.
Version History:: https://github.com/webscreens/presentation-api/commits/
Editors:: Dominik Röttsches, Intel; 闵洪波 (Hongbo Min), Intel

Copyright © 2014 the Contributors to the Presentation API Specification, published by the Second Screen Presentation Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

Abstract

This specification defines an API to enable web content to access external presentation-type displays and use them for presenting web content.

Status of this Document

This specification was published by the Second Screen Presentation Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1 Introduction

This section is non-normative.

This specification aims to make secondary displays such as a projector or a connected TV available to the web and takes into account displays that are attached using wired (HDMI, DVI or similar) and wireless technologies (MiraCast, DLNA, AirPlay or similar).

Devices with limited screen size lack the ability to show content to a larger audience, for example a group of colleagues in a conference room, or friends and family at home. Showing content on an external large display helps to improve the perceived quality and impact of the presented content.

It is the intention of this specification that the user agent prepares a rendering for the secondary display in a way that is adapted to the secondary display's capabilities. The DOM state and the rendering shown on the primary and secondary display are maintained and performed by the same user agent. There is no secondary user agent involved that would run remotely on the secondary display.

The user agent creates two browsing contexts, one on the primary display, one on the selected presentation display. It is responsible for sending the rendered output to the secondary display. For wirelessly-connected displays this may mean that the user agent prepares a video stream from the rendering output that is sent over the network to the wireless display.

The trend in user agent implementations has been to avoid opening multiple separate windows and containing window management to tabs, which helps the user to organize multiple pages. However, the following example use cases fall outside the regular management of multiple windows for web pages.

1.1 Use Cases

1.1.1 Presentations

A user is preparing a set of slides for a talk. Using a web based service, she is editing her slides and speaker notes on the primary screen, while the secondary larger screen shows a preview of the current slide. When the slides are done, her mobile phone allows her to access them from an online service while on the go. Coming to the conference, using wireless display technology, she would like to present her slides on the stage screen from her mobile phone. The phone's touch screen helps her to navigate slides and presents a slide preview, while the projector shows her slides to the audience.

Using an online video or image sharing service, a user would like to show memorable moments to her friends. Using a device with a small screen, it is impossible to show the content to a large group of people. Connecting an external TV screen or projector to her device - with a cable or wirelessly - the online sharing service now makes use of the connected display, allowing a wider audience to enjoy the content.

1.1.3 Gaming

Splitting the gaming experience into a near screen controller and a large screen visual experience, new gaming experiences can be created. Accessing the local display on the small screen device and an external larger display allows for richer web-based gaming experiences.

1.2 Example

Running in a compliant user agent, code for playing a video on the presentation display could look like the following:

/* player.html */

<video>
<script>
var v = document.querySelector('video');

window.onmessage = function (event) {
  v.src = event.data;
  v.play();
};
</script>

/* controller.html */

<script>
function playVideo() {
  if (!navigator.presentation.displayAvailable)
    return;
  var p = navigator.presentation.requestShow('player.html');
  p.then(function (display) { display.postMessage('http://example.org/video.mp4', '/'); },
         function (error) { console.log('Request to show failed: ' + error.msg); }
  );
}

playVideo();

</script>

In this example of a video player scenario similar to the video sharing use case presented above, the opener browsing context loads a document into the presentation browsing context which has a video element in it and communicates with it through postMessage. The document of the presentation browsing context receives the commands and for example sets the src attribute of the video and starts playing it.

The example uses postMessage for communication between opener and auxiliary browsing context in order to encourage the use of asynchronous, potentially cross-origin communication between the two contexts. Direct access to properties of the document object in the auxiliary browsing context is an alternative option in case the documents are loaded from the same origin.

<script>

/* Monitoring availability */
navigator.presentation.ondisplayavailablechange = function() {
  /* For example: Enable/Disable UI to show content on presentation display here. */
  var availability = navigator.presentation.displayAvailable ? "available" : "unavailable";
  console.log("Presentation display is now " + availability + ".");
}

</script>

This example demonstrates the auxiliary use case of monitoring for available secondary displays in order to keep the UI consistent. The displayavailablechange event informs about displays appearing or disappearing and allows the client of the API to update page content accordingly.

2 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and terminate these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc.) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

3 Terminology

The term presentation display refers to an external screen connected to the device that the user agent runs on.

The terms opener browsing context and auxiliary browsing context are defined in [HTML5].

The terms event handlers and event handler event types are defined in [HTML5].

The Promises model and the concept of event firing are defined in the [DOM] living standard.

This document provides interface definitions using the [WEBIDL] standard.

The basic fetch algorithm is defined in [FETCH].

4 Presentation Extension to Navigator

partial interface Navigator {
  readonly attribute Presentation presentation;

};

5 Presentation Interface

interface Presentation : EventTarget {
  Promise requestShow(optional DOMString url = "about:blank");

  readonly attribute boolean displayAvailable;
  attribute EventHandler ondisplayavailablechange;
};

requestShow

Method to request opening and showing a new browsing context on the selected presentation display.

Parameters:

optional DOMString url: URL of the page that is to be loaded in the new browsing context.

Returns:

Promise: Promise that is fulfilled when the request was successful, rejected if it failed.

displayAvailable

A boolean flag to indicate the secondary display availability in the UA. Updated when the display availability changes. True if there is at least one available secondary display for the mentioned use cases, false otherwise.

6 Display Selection and Availability

If at least one event listener is registered to the ondisplayavailablechange event handler the user agent should start monitoring for the availability of secondary displays suitable for the for the mentioned use cases.

When there are no more event listeners attached to the ondisplayavailablechange event handler, the user agent may stop such monitoring for the availability of secondary displays.

This includes displays connected to the user agent's system via wired connections (e.g. HDMI, DVI etc.) as well as via wireless technologies (e.g. MiraCast, DLNA or similar) that use a local or personal area network as a transport mechanism. The discovery can be performed by using operating system APIs that notify the user agent about display configuration changes or by means of network discovery for remote display technologies that are not handled by the operating system. In the latter case, the user agent or the operating system that the user agent runs on may prepare a video stream suitable for being decoded and displayed by the wirelessly-connected display.

6.1 Monitoring for Availability Changes

When a user agent is to monitor for the availability of secondary displays, it must execute the following steps.

Let currentDisplayFound be a boolean representing whether there are one more secondary displays available right now and let currentDisplayFound be false if it was not previously set.
Query for available secondary displays that the user agent has access to.

An implementation of this API may chose to use operating system screen & display information APIs or start an implementation dependent network discovery process.
Set displayAvailable to true if at least one suitable display was found in step 2, set to false otherwise.
If displayAvailable is different from currentDisplayFound, fire a new event displayavailablechange at the navigator.presentation object.
Set currentDisplayFound to displayAvailable.
Continue at step 1.

It is left to the implementation to determine a suitable polling/monitoring frequency or alternatively using notification mechanisms of the host OS for display availability changes.

7 Requesting a Presentation Display

When requesting a presentation display, the user agent returns a Promise and asynchronously goes through the steps needed to open access to that display. The UA needs to check for availability. If a display is available, the user agent asks the user for permission to use and select one. Then it can open a new browsing context on that display and fulfils the Promise with the WindowProxy object of the new auxiliary browsing context as the value of the Promise, otherwise rejects the Promise with an error.

A user agent shall only open and maintain a maximum of one presentation browsing context per available secondary display. If requestShow is called a second time and the user selects an available display that was previously in use by a previous call to requestShow, the user agent shall close the previous browsing context.

When the requestShow method is called, the user agent must execute the following algorithm to request access to the presentation display:

Let promise be a new Promise.
Return promise and run the following steps asynchronously.
Verify that the availability monitoring algorithm is running and that the value of displayAvailable is true. If it is false or the algorithm is not running, jump to the step labeled failure below.
Prompt the user's permission or check that the setting for allowing access to a presentation display enabled. If no permission is given, jump to the step labeled failure below. If the user never responds, this algorithm will never progress beyond this step.
If more than one available display is found, present a selection to the user for choosing one of the available display.
If the user cancels the selection, go to the failure step.
Let the display that the user selected be called selected presentation display.
If there is already a presentation browsing context opened on the selected presentation display, close the existing presentation browsing context.
Open a new auxiliary browsing context and present it fullscreen on the selected presentation display. The newly created auxiliary browsing context is called presentation browsing context.
Resolve the url to an absolute URL relative to the entry script's base URL. Let resolvedUrl be the result of this resolution.
If the URL resolution fails, go to the failure step.
Navigate the presentation browsing context to resolvedUrl with the browsing context of the incumbent script as the source browsing context.
Success: Fulfil promise with the WindowProxy of the new presentation browsing context as its value.
Terminate these steps.
Failure: Let error be a new DOMError. The user agent must determine the error type in the following order of priority:

If the user has denied permission to open a presentation display, error must be of type SecurityError.
error must be of type NotSupportedError.

Reject promise with error as its value.

8 Lifecycle and Visibility of the Presentation Window

8.1 User Closing the Presentation Window

The user agent should provide a means for the user to close the presentation browsing context.

In a PC scenario, this could be by means of an overlay on the secondary display with a close icon. In a mobile scenario where the user has no means of using a mouse cursor or other interaction with the secondary display, it could be an icon on the primary display.

If the user closes the presentation browsing context, the user agent should follow the regular algorithm for closing a browsing context.

This means, that the opener browsing context can register an onunload EventHandler on the presentation browsing context to detect when the window gets closed.

There are currently two open issues: A user of this API can subscribe to the onunload event of the presentation browsing context's Window object but this event only fires if the URL loaded in the presentation browsing context's is from the same origin. Secondly, there is no such thing as an onerror event if the presentation browsing context is closed unexpectedly.

8.2 Programmatic Closing of the Presentation Window

Similarly, when the close() method of the WindowProxy is called, the user agent must behave as specified in the steps for the close() method of the Window object.

8.3 Display Availability Changes

If the display configuration of the user agent's host system changes so that the secondary display is not available any more, or if a display connected via the network becomes unreachable, and the user agent was showing an existing presentation browsing context on the display which is now unavailable, the user agent should follow the regular algorithm for closing a browsing context.

8.4 Close on Unload

When the browsing context from which one or more presentation browsing contexts were opened is getting closed, the user agent should close all presentation browsing contexts that it opened.

9 Security Considerations

The widespread use of popup blockers shows that the window.open() functionality was often abused to interrupt the user's workflow with unsolicited advertising. It is clear that repeating this story should be avoided. Hence, when implementing this specification, user agents shall give clear indication to the user that a site is requesting to open a presentation display. User agents may prompt the user to give consent to displaying content on the selected presentation display.

User Agents may provide a setting which prevents pages from using a presentation display altogether.

Opening the presentation browsing context follows the legacy behavior of window.open() and thus allows navigating to URLs that are not at the same origin as the browsing context of the incumbent script. This does not introduce any new security issues in itself. However, it would be desirable to only navigate to URLs in the presentation browsing context using the basic fetch algorithm with the CORS flag flag set to true, but this would require changes to or a local redefinition of the navigation algorithm.

References

[DOM]: DOM, Anne van Kesteren, Aryeh Gregor and Ms2ger. WHATWG.
[FETCH]: Fetch, Anne van Kesteren. WHATWG.
[HTML5]: HTML5, Robin Berjon, Steve Faulkner, Travis Leithead et al.. W3C.
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[WEBIDL]: Web IDL, Cameron McCormack. W3C.

Acknowledgements

Thanks to Wayne Carr and Anssi Kostiainen for input, thorough reviews and feedback to this draft.