This specification defines an API to enable Web content to access
presentation displays and use them for presenting Web content.

Since publication as Candidate Recommendation on 14 July
2016, the Working Group updated most algorithms in the spec to fix
issues identified through testing and implementation feedback.
Interfaces defined in this document did not change, except
PresentationConnectionClosedReason and
PresentationConnectionClosedEvent, which were renamed to
improve consistency with the rest of the Web platform. The API was also
restricted to secure contexts. See the list of changes for details.

Introduction

The Presentation API aims to make presentation displays such as
projectors, attached monitors, and network-connected TVs available to
the Web. It takes into account displays that are attached using wired
(HDMI, DVI, or similar) and wireless technologies (Miracast,
Chromecast, DLNA, AirPlay, or similar).

Devices with limited screen size lack the ability to show Web content
to a larger audience: a group of colleagues in a conference room, or
friends and family at home, for example. Web content shown on a larger
presentation display has greater perceived quality, legibility,
and impact.

At its core, the Presentation API enables a controller page to
show a presentation page
on a presentation display and exchange messages with it. How the
presentation page is transmitted to the display and how messages are
exchanged between it and the controller page are left to the
implementation; this allows the use of a wide variety of display
technologies.

For example, if the presentation display is connected by HDMI or
Miracast, which only allow audio and video to be transmitted, the user
agent (UA) hosting the controller will also render the presentation. It then uses the
operating system to send the resulting graphical and audio output to
the presentation display. We refer to this situation as the
1-UA mode implementation of the Presentation
API. The only requirements are that the user agent is able to send
graphics and audio from rendering the presentation to the presentation
display, and exchange messages internally between the controller and
presentation pages.

If the presentation display is able to render HTML natively and
communicate with the controller via a network, the user agent
hosting the controller does not need to render the presentation. Instead, the user
agent acts as a proxy that requests the presentation display to load
and render the presentation page itself. Message exchange is done over
a network connection between the user agent and the presentation
display. We refer to this situation as the 2-UA
mode implementation of the Presentation API.

The Presentation API is intended to be used with user agents that
attach to presentation displays in 1-UA mode, 2-UA
mode, and possibly other means not listed above. To improve
interoperability between user agents and presentation displays,
standardization of network communication between browsers and displays
is being considered in the Second Screen Community
Group.

Use cases and requirements

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 result is equivalent. (In
particular, the algorithms defined in this specification are intended
to be easy to follow, and not intended to be performant.)

Conformance classes

This specification describes the conformance criteria for two classes
of user agents.

Examples

This section shows example codes that highlight the usage of main
features of the Presentation API. In these examples,
controller.html implements the controller and
presentation.html implements the presentation. Both pages
are served from the domain https://example.org
(https://example.org/controller.html and
https://example.org/presentation.html). These examples
assume that the controlling page is managing one presentation at a
time. Please refer to the comments in the code examples for further
details.

Monitor availability of presentation displays example

<!-- controller.html -->
<button id="presentBtn" style="display: none;">Present</button>
<script>
// The Present button is visible if at least one presentation display is available
var presentBtn = document.getElementById("presentBtn");
// It is also possible to use relative presentation URL e.g. "presentation.html"
var presUrls = ["https://example.com/presentation.html",
"https://example.net/alternate.html"];
// show or hide present button depending on display availability
var handleAvailabilityChange = function(available) {
presentBtn.style.display = available ? "inline" : "none";
};
// Promise is resolved as soon as the presentation display availability is
// known.
var request = new PresentationRequest(presUrls);
request.getAvailability().then(function(availability) {
// availability.value may be kept up-to-date by the controlling UA as long
// as the availability object is alive. It is advised for the Web developers
// to discard the object as soon as it's not needed.
handleAvailabilityChange(availability.value);
availability.onchange = function() { handleAvailabilityChange(this.value); };
}).catch(function() {
// Availability monitoring is not supported by the platform, so discovery of
// presentation displays will happen only after request.start() is called.
// Pretend the devices are available for simplicity; or, one could implement
// a third state for the button.
handleAvailabilityChange(true);
});
</script>

Some presentation displays may only be able to display a
subset of Web content because of functional, security or hardware
limitations. Examples are set-top boxes, smart TVs, or networked
speakers capable of rendering only audio. We say that such a display
is an available
presentation display for a presentation URL if the
controlling user agent can reasonably guarantee that
presentation of the URL on that display will succeed.

The details of implementing the permission request and display
selection are left to the user agent; for example it may show the
user a dialog and allow the user to select an available display
(granting permission), or cancel the selection (denying
permission). Implementers are encouraged to show the user whether
an available display is currently in use, to facilitate
presentations that can make use of multiple displays.

Receiving user agents are encouraged to advertise a user friendly
name for the presentation display, e.g. "Living Room TV",
to assist the user in selecting the intended display. Implementers
of receiving user agents are also encouraged to advertise the
locale and intended text direction of the user friendly name.
Implementers of controlling user agents are encouraged to render a
user friendly name using its locale and text direction when they
are known.

Starting a presentation from a default presentation request

When the user expresses an intent to start presentation of a
document on a presentation display using the browser chrome (via a
dedicated button, user gesture, or other signal), that user agent
MUST run the following steps to start
a presentation from a default presentation request. If no
default presentation request is set on the document, these
steps MUST not be run.

Input

W, the document on which the user has expressed an
intent to start presentation

The presentationUrl should name a resource accessible to
the local or a remote user agent. This specification defines
behavior for presentationUrl using the http
or https schemes; behavior for other schemes is not
defined by this specification.

Reconnecting to a presentation

When the reconnect
method is called, the user agent MUST run the following
steps to reconnect to a presentation:

Event Handlers

The following are the event handlers (and their corresponding event
handler event types) that must be supported, as event handler IDL
attributes, by objects implementing the PresentationRequest
interface:

The binaryType attribute can take one of the values of
BinaryType. When a
PresentationConnection object is created, its
binaryType attribute MUST be set to the string "arraybuffer". On getting, it MUST return the last
value it was set to. On setting, the user agent MUST set the
attribute to the new value.

The binaryType attribute allows authors to control how
binary data is exposed to scripts. By setting the attribute to
"blob", binary data is
returned in Blob form; by setting it to "arraybuffer", it is returned in
ArrayBuffer form. The attribute defaults to
"arraybuffer". This attribute has no effect on data
sent in a string form.

The mechanism that is used to present on the remote display and
connect the controlling browsing context with the presented
document is an implementation choice of the user agent. The
connection must provide a two-way messaging abstraction capable of
carrying DOMString and binary payloads in a reliable
and in-order fashion as described in the Send a Message and
Receive a Message steps below.

If the previous step encounters an unrecoverable error, then
abruptly close the presentation connectionpresentationConnection with error as
closeReason, and a closeMessage describing
the error encountered.

To assist applications in recovery from an error sending a
message through a presentation connection, the user agent
should include details of which attempt failed in
closeMessage, along with a human readable string
explaining the failure reason. Example renditions of
closeMessage:

Unable to send text message (network_error):
"hello" for DOMString messages, where
"hello" is the first 256 characters of the failed
message.

When sending a user-visible string via a presentation
connection, the page author should take care to ensure that
locale information is also propagated so that the destination user
agent can know how to best render the string. See the examples for
one solution.

This could happen by an explicit user action, or as a policy of
the user agent. For example, the receiving user agent
could be configured to terminate presentations whose
PresentationConnection objects are all closed for 30
minutes.

Event Handlers

The following are the event handlers (and their corresponding event
handler event types) that must be supported, as event handler IDL
attributes, by objects implementing the
PresentationConnection interface:

This algorithm is intended to create a well defined environment to
allow interoperable behavior for 1-UA and 2-UA
presentations, and to minimize the amount of state remaining on a
presentation display used for a 2-UA presentation.

Event Handlers

The following are the event handlers (and their corresponding event
handler event types) that must be supported, as event handler IDL
attributes, by objects implementing the
PresentationConnectionList interface:

Event handler

Event handler event type

onconnectionavailable

connectionavailable

Security and privacy considerations

Personally identifiable information

The change event fired on the PresentationAvailability
object reveals one bit of information about the presence or absence
of a presentation display, often discovered through the
browser's local area network. This could be used in conjunction with
other information for fingerprinting the user. However, this
information is also dependent on the user's local network context, so
the risk is minimized.

Cross-origin access

A presentation is
allowed to be accessed across origins; the presentation URL
and presentation identifier used to create the presentation
are the only information needed to reconnect to a presentation from
any origin in the controlling user agent. In other words, a
presentation is not tied to a particular opening origin.

This design allows controlling contexts from different origins to
connect to a shared presentation resource. The security of the
presentation identifier prevents arbitrary origins from connecting to
an existing presentation.

This specification makes no guarantee as to the identity of any party
connecting to a presentation. Once connected, the presentation may
wish to further verify the identity of the connecting party through
application-specific means. For example, the presentation could
challenge the controller to provide a token via send that the presentation uses to
verify identity and authorization.

Display of the origin requesting presentation will help the user
understand what content is making the request, especially when
the request is initiated from a nested browsing context.
For example, embedded content may try to convince the user to
click to trigger a request to start an unwanted presentation.

When a user starts a
presentation, the user will begin with exclusive control of
the presentation. However, the Presentation API allows additional
devices (likely belonging to distinct users) to connect and
thereby control the presentation as well. When a second device
connects to a presentation, it is recommended that all connected
controlling user agents
notify their users via the browser chrome that the original user
has lost exclusive access, and there are now multiple controllers
for the presentation.

Device Access

The presentation API abstracts away what "local" means for displays,
meaning that it exposes network-accessible displays as though they
were directly attached to the user's device. The Presentation API
requires user permission for a page to access any display to mitigate
issues that could arise, such as showing unwanted content on a
display viewable by others.

Temporary identifiers and browser state

The presentation URL and presentation identifier can be
used to connect to a presentation from another browsing context. They
can be intercepted if an attacker can inject content into the
controlling page.

Private browsing mode and clearing of browsing data

The content displayed on the presentation is different from the
controller. In particular, if the user is logged in in both contexts,
then logs out of the controlling browsing context, she will
not be automatically logged out from the receiving browsing
context. Applications that use authentication should pay extra
care when communicating between devices.

The set of presentations known to the user agent should be cleared
when the user requests to "clear browsing data."

AirPlay, HDMI, Chromecast, DLNA and
Miracast are registered trademarks of Apple Inc., HDMI
Licensing LLC., Google Inc., the Digital Living Network Alliance, and
the Wi-Fi Alliance, respectively. They are only cited as background
information and their use is not required to implement the
specification.

Candidate Recommendation exit criteria

For this specification to be advanced to Proposed Recommendation, there
must be, for each of the conformance classes it defines (controlling
user agent and receiving user agent), at least two
independent, interoperable implementations of each feature. Each
feature may be implemented by a different set of products, there is no
requirement that all features be implemented by a single product.
Additionally, implementations of the controlling user agent
conformance class must include at least one implementation of the
1-UA mode, and one implementation of the 2-UA
mode. 2-UA mode implementations may only support non
http/https presentation URLs. Implementations of the receiving user
agent conformance class may not include implementations of
the 2-UA mode.

The API was recently restricted to secure contexts. Deprecation of the
API in non secure contexts in early implementations takes time. The
group may request transition to Proposed Recommendation with
implementations that still expose the API in non secure contexts,
provided there exists a timeline to restrict these implementations in
the future.

For the purposes of these criteria, we define the following terms:

Independent

Each implementation must be developed by a different party, and
cannot share, reuse, or derive from code used by another qualifying
implementation. Sections of code that have no bearing on the
implementation of this specification are exempt from this
requirement.

Interoperable

Passing the respective test case(s) in the official test suite.

Implementation

A user agent which:

implements one of the conformance classes of the specification.

is available to the general public. The implementation may be a
shipping product or other publicly available version (i.e., beta
version, preview release, or "nightly build"). Non-shipping product
releases must have implemented the feature(s) for a period of at
least one month in order to demonstrate stability.

is not experimental (i.e. a version specifically designed to
pass the test suite and not intended for normal usage going
forward).

Change log

This section lists changes made to the spec since it was first
published as Candidate Recommendation in July 2016, with links to
related issues on the group's issue tracker.

The sandboxed top-level navigation browsing context flag and the
sandboxed modals flag are now set on the receiving browsing context
to prevent top-level navigation and the ability to spawn new browsing
contexts (#414)