This specification defines an API to enable web content to access external presentation-type displays and use them for presenting web content.
Since publication as Working Draft on 10 May 2016, the Working Group has added a new URL fallback mechanism for requests to initiate or reconnect to a presentation, re-written the algorithm to create a receiving browsing context, clarified interactions between iframes and the sandboxing flag, and resolved to postpone new features currently mentioned in the group's issue tracker to a possible future version. The Working Group also made further progress on the test suite.
No feature has been identified as being at risk. However, the working group notes that it expects the definitions in the section to be integrated in HTML (see issue #437 in the Web Platform Working Group issue tracker) and dropped from this specification.
The Second Screen Presentation Working Group will complete the test suite for the Presentation API during the Candidate Recommendation period and update the preliminary implementation report. For this specification to advance to Proposed Recommendation, two independent, interoperable implementations of each feature must be demonstrated, as detailed in the CR exit criteria section.
This specification aims to make presentation displays such as projectors or connected TVs, available to the Web and 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 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 presentation display helps to improve the perceived quality and impact of the presented content.
At its core, this specification enables an exchange of messages between a page that acts as the controller and another page that represents the presentation shown in the presentation display. How the messages are transmitted is left to the UA in order to allow the use of presentation display devices that can be attached in a wide variety of ways. For example, when a presentation display device is attached using HDMI or Miracast, the same UA that acts as the controller renders the presentation. Instead of displaying the presentation in another window on the same device, however, it can use whatever means the operating system provides for using the external presentation displays. In such a case, both the controller and presentation run on the same UA and the operating system is used to route the presentation display output to the presentation display. This is commonly referred to as the 1-UA case. This specification imposes no requirements on the presentation display devices connected in such a manner.
If the presentation display is able to render HTML documents and communicate with the controller, the controller does not need to render the presentation. In this case, the UA acts as a proxy that requests the presentation display to show and render the presentation itself. This is commonly referred to as the 2-UA case. This way of attaching to displays could be enhanced in the future by defining a standard protocol for delivering these types of messages that display devices could choose to implement.
The API defined here is intended to be used with UAs that attach to presentation display devices through any of the above means.
Use cases and requirements are captured in a separate Presentation API Use Cases and Requirements document.
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.)
This specification describes the conformance criteria for two classes of user agents.
Web browsers that conform to the specifications of a
controlling user agent must be able to start and control
presentations by providing a controlling browsing context
as described in this specification. This context implements the
Presentation,
PresentationAvailability,
PresentationConnection,
PresentationConnectionAvailableEvent,
PresentationConnectionCloseEvent, and
PresentationRequest interfaces.
Web browsers that conform to the specifications of a receiving
user agent must be able to render presentations by providing
a receiving browsing context as described in this
specification. This context implements the
Presentation,
PresentationConnection,
PresentationConnectionAvailableEvent,
PresentationConnectionCloseEvent,
PresentationConnectionList, and
PresentationReceiver interfaces.
One user agent may act both as a controlling user agent and as a receiving user agent, if it provides both browsing contexts and implements all of their required interfaces. This can happen when the same user agent is able to host the controlling browsing context and the receiving browsing context for a presentation, as in the 1-UA implementation of the API.
Conformance requirements phrased against a user agent apply either to a controlling user agent, a receiving user agent or to both classes, depending on the context.
The terms application
cache, browsing
context, nested
browsing context, event
handler, event
handler event type, firing
an event, firing
a simple event, navigate,
queue a
task,
trusted event, allowed
to show a popup, top-level
browsing context, unload a
document, session
history, sandboxing
flag set, active
sandboxing flag set,
parse a sandboxing directive,
sandboxed auxiliary navigation browsing context flag,
sandboxed top-level navigation browsing context flag,
EventHandler
and Navigator
are defined in [[!HTML5]].
The terms in parallel and task source are defined in [[!HTML51]].
The terms EventTarget,
Event,
EventInit
are defined in [[!DOM]].
This document provides interface definitions using the Web IDL standard ([[!WEBIDL]]). The terms Promise, ArrayBuffer, ArrayBufferView are defined in [[!WEBIDL]].
The term throw in this specification is used as defined in [[!WEBIDL]]. The following exception names are defined by WebIDL and used by this specification:
NotAllowedError
InvalidAccessError
NotFoundError
NotSupportedError
OperationError
SecurityError
SyntaxError
The terms resolving a Promise and rejecting a Promise are used as explained in [[!PROMGUIDE]].
The term URL is defined in the WHATWG URL standard [[!URL]].
The terms current settings object and relevant settings object are defined in [[HTML]].
The term Blob is defined in the File API specification [[!FILEAPI]].
The header Accept-Language is defined in HTTP/1.1 [[rfc7231]].
HTTP authentication is defined in HTTP/1.1: Authentication [[!rfc7235]].
The term RTCDataChannel is defined in the WebRTC API specification [[WEBRTC]].
The term cookie store is defined in RFC 6265 [[COOKIES]].
The term UUID is defined in RFC 4122 [[rfc4122]].
The terms permission and permission state are defined in [[!PERMISSIONS]].
The term database is defined in [[!INDEXEDDB]].
The terms local storage areas and session storage areas are defined in [[!WEBSTORAGE]].
The terms potentially secure, a priori unauthenticated URL, and prohibits mixed security contexts algorithm are defined in [[!MIXED-CONTENT]].
The terms service worker, a list of registered service worker registrations, caches, window client and worker client are defined in [[!SERVICE-WORKERS]].
The term DIAL is defined in [[DIAL]].
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 http://example.org
(http://example.org/controller.html and
http://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.
<!-- 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 = ["http://example.com/presentation.html",
"http://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>
<!-- controller.html -->
<script>
presentBtn.onclick = function () {
// Start new presentation.
request.start()
// The connection to the presentation will be passed to setConnection on
// success.
.then(setConnection);
// Otherwise, the user canceled the selection dialog or no screens were
// found.
};
</script>
<!-- controller.html -->
<button id="reconnectBtn" style="display: none;">Reconnect</button>
<script>
var reconnect = function () {
// read presId from localStorage if exists
var presId = localStorage["presId"];
// presId is mandatory when reconnecting to a presentation.
if (!!presId) {
request.reconnect(presId)
// The new connection to the presentation will be passed to
// setConnection on success.
.then(setConnection);
// No connection found for presUrl and presId, or an error occurred.
}
};
// On navigation of the controller, reconnect automatically.
document.addEventListener("DOMContentLoaded", reconnect);
// Or allow manual reconnection.
const reconnectBtn = document.querySelector("#reconnectBtn");
reconnectBtn.onclick = reconnect;
</script>
<!-- controller.html -->
<!-- Setting presentation.defaultRequest allows the page to specify the
PresentationRequest to use when the controlling UA initiates a
presentation. -->
<script>
navigator.presentation.defaultRequest = new PresentationRequest(presUrls);
navigator.presentation.defaultRequest.onconnectionavailable = function(evt) {
setConnection(evt.connection);
};
</script>
<!-- controller.html -->
<button id="disconnectBtn" style="display: none;">Disconnect</button>
<button id="stopBtn" style="display: none;">Stop</button>
<script>
let connection;
// The Disconnect and Stop buttons are visible if there is a connected presentation
const stopBtn = document.querySelector("#stopBtn");
const disconnectBtn = document.querySelector("#disconnectBtn");
stopBtn.onclick = _ => {
connection && connection.terminate();
};
disconnectBtn.onclick = _ => {
connection && connection.close();
};
function setConnection(newConnection) {
// Disconnect from existing presentation, if not attempting to reconnect
if (connection && connection != newConnection && connection.state != 'closed') {
connection.onclosed = undefined;
connection.close();
}
// Set the new connection and save the presentation ID
connection = newConnection;
localStorage["presId"] = connection.id;
function showConnectedUI() {
// Allow the user to disconnect from or terminate the presentation
stopBtn.style.display = "inline";
disconnectBtn.style.display = "inline";
reconnectBtn.style.display = "none";
}
function showDisconnectedUI() {
disconnectBtn.style.display = "none";
stopBtn.style.display = "none";
reconnectBtn.style.display = localStorage["presId"] ? "inline" : "none";
}
// Monitor the connection state
connection.onconnect = _ => {
showConnectedUI();
// Register message handler
connection.onmessage = message => {
console.log(`Received message: ${message.data}`);
};
// Send initial message to presentation page
connection.send("Say hello");
};
connection.onclose = _ => {
connection = null;
showDisconnectedUI();
};
connection.onterminate = _ => {
// Remove presId from localStorage if exists
delete localStorage["presId"];
connection = null;
showDisconnectedUI();
};
};
</script>
<!-- presentation.html -->
<script>
var addConnection = function(connection) {
this.onmessage = function (message) {
if (message.data == "say hello")
this.send("hello");
};
};
navigator.presentation.receiver.connectionList.then(function (list) {
list.connections.map(function (connection) {
addConnection(connection);
});
list.onconnectionavailable = function (evt) {
addConnection(evt.connection);
};
});
</script>
<!-- controller.html -->
<script>
connection.send("{string: '你好，世界!', lang: 'zh-CN'}");
connection.send("{string: 'こんにちは、世界!', lang: 'ja'}");
connection.send("{string: '안녕하세요, 세계!', lang: 'ko'}");
connection.send("{string: 'Hello, world!', lang: 'en-US'}");
</script>
<!-- presentation.html -->
<script>
connection.onmessage = function (message) {
var messageObj = JSON.parse(message.data);
var spanElt = document.createElement("SPAN");
spanElt.lang = messageObj.lang;
spanElt.textContent = messageObj.string;
document.appendChild(spanElt);
};
</script>
A presentation display refers to an external screen available to the user agent via an implementation specific connection technology.
A presentation connection is an object relating a controlling browsing context to its receiving browsing context and enables two-way-messaging between them. Each presentation connection has a presentation connection state, a unique presentation identifier to distinguish it from other presentations, and a presentation URL that is a URL used to create or reconnect to the presentation. A valid presentation identifier consists of alphanumeric ASCII characters only and is at least 16 characters long.
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 URL if the controlling user agent can reasonably guarantee that the presentation of the URL on that display will succeed.
A controlling
browsing context (or controller for short) is a
browsing context that has connected to a presentation
by calling start() or
reconnect(), or
received a presentation connection via a connectionavailable event.
The receiving browsing context (or presentation for short) is the browsing context responsible for rendering to a presentation display. A receiving browsing context can reside in the same user agent as the controlling browsing context or a different one. A receiving browsing context is created by following the steps to create a receiving browsing context.
In a procedure, the destination browsing context is the receiving browsing context when the procedure is initiated at the controlling browsing context, or the controlling browsing context if it is initiated at the receiving browsing context.
The set of controlled presentations, initially empty, contains the presentation connections created by the controlling browsing contexts for the controlling user agent (or a specific user profile within that user agent). The set of controlled presentations is represented by a list of PresentationConnection objects that represent the underlying presentation connections. Several PresentationConnection objects may share the same presentation URL and presentation identifier in that set, but there can be only one PresentationConnection with a specific presentation URL and presentation identifier for a given controlling browsing context.
The set of presentation controllers, initially empty, contains the presentation connections created by a receiving browsing context for the receiving user agent. The set of presentation controllers is represented by a list of PresentationConnection objects that represent the underlying presentation connections. All presentation connections in this set share the same presentation URL and presentation identifier.
In a receiving browsing context, the presentation
controllers monitor, initially set to null,
exposes the current set of presentation controllers to the
receiving application. The presentation controllers monitor is
represented by a PresentationConnectionList.
In a receiving browsing context, the presentation
controllers promise, which is initially set to
null, provides the presentation controllers
monitor once the initial presentation connection is
established. The presentation controllers promise is
represented by a Promise that resolves with the
presentation controllers monitor.
In a controlling browsing context, the default
presentation request, which is initially set to
null, represents the request to use when the user wishes
to initiate a presentation connection from the browser chrome.
The task source for the tasks mentioned in this specification is the presentation task source.
Presentation
partial interface Navigator {
[SameObject] readonly attribute Presentation presentation;
};
interface Presentation {
};
The presentation attribute is
used to retrieve an instance of the Presentation
interface. It MUST return the Presentation
instance.
Controlling user agents MUST implement the following partial interface:
partial interface Presentation {
attribute PresentationRequest? defaultRequest;
};
The defaultRequest
attribute MUST return the default presentation request if
any, null otherwise. On setting, the default
presentation request MUST be set to the new value.
The controlling user agent SHOULD initiate presentation using the default presentation request only when the user has expressed an intention to do so via a user gesture, for example by clicking a button in the browser chrome.
To initiate presentation using the default presentation request, the controlling user agent MUST follow the steps to start a presentation from a default presentation request.
Support for initiating a presentation using the default presentation request is OPTIONAL.
defaultRequest.
Receiving user agents MUST implement the following partial interface:
partial interface Presentation {
readonly attribute PresentationReceiver? receiver;
};
The receiver attribute
MUST return the PresentationReceiver instance
associated with the receiving browsing context and created
by the receiving user agent when the receiving browsing
context is created. In any other browsing context, it
MUST return null.
Web developers can use Navigator.presentation.receiver
to detect when a document is loaded as a presentation.
PresentationRequest
[Constructor(USVString url),
Constructor(sequence<USVString> urls)]
interface PresentationRequest : EventTarget {
Promise<PresentationConnection> start();
Promise<PresentationConnection> reconnect(USVString presentationId);
Promise<PresentationAvailability> getAvailability();
attribute EventHandler onconnectionavailable;
};
A PresentationRequest object is associated with a
request to initiate or reconnect to a presentation made by a
controlling browsing context. The
PresentationRequest object MUST be implemented in
a controlling browsing context provided by a controlling
user agent.
When a PresentationRequest is constructed, the
given urls MUST be used as the list of presentation request URLs which are
each a possible presentation URL for the
PresentationRequest instance.
PresentationRequest
When the PresentationRequest constructor is called,
the controlling user agent MUST run these steps:
PresentationRequest object
"Prohibits Mixed
Security Contexts" and any member of
presentationUrls is an a priori unauthenticated
URL, then throw a SecurityError and abort these steps.
PresentationRequest object with
presentationUrls as its presentation request URLs
and return it.
When the start
method is called, the user agent MUST run the following
steps to select a presentation display.
PresentationRequest object that received the call to
start
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.
null value
of navigator.presentation.defaultRequest set on
W
When the user agent is to start a presentation connection, it MUST run the following steps:
PresentationRequest that is used to start the
presentation connection
http
or https schemes; behavior for other schemes is not
defined by this specification.
When the reconnect(presentationId) method
is called on a PresentationRequest
presentationRequest, the user agent MUST run the
following steps to reconnect to a presentation:
reconnect() was called on
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:
| Event handler | Event handler event type |
|---|---|
onconnectionavailable
|
connectionavailable
|
PresentationAvailability
interface PresentationAvailability : EventTarget {
readonly attribute boolean value;
attribute EventHandler onchange;
};
A PresentationAvailability object exposes the
presentation display availability for a presentation request.
The presentation display availability for a
PresentationRequest stores whether there is currently
any available presentation display for at least one of the
presentation request URLs of the request.
The presentation display availability for a presentation
request is eligible for garbage collection when no ECMASCript code
can observe the PresentationAvailability object.
If the controlling user agent can monitor the list of
available presentation displays in the background (without a
pending request to start()), the
PresentationAvailability object MUST be
implemented in a controlling browsing context.
The value attribute MUST return the last value it was set to. The value is initialized and updated by the monitor the list of available presentation displays algorithm.
The onchange attribute is
an event handler whose corresponding event handler event
type is change.
The user agent MUST keep track of the set of
presentation availability objects created by the
getAvailability()
method. The set of presentation availability objects is
represented as a set of tuples (A,
availabilityUrls), initially empty, where:
PresentationAvailability
object.
PresentationRequest when
getAvailability()
was called on it to create A.
The user agent MUST keep a list of available presentation displays. The list of available presentation displays is represented by a list of tuples (availabilityUrl, display). An entry in this list means that display is currently an available presentation display for availabilityUrl. This list of presentation displays may be used for starting new presentations, and is populated based on an implementation specific discovery mechanism. It is set to the most recent result of the algorithm to monitor the list of available presentation displays.
While the set of presentation availability objects is not
empty, the user agent MAY monitor the list of available
presentation displays continuously, so that pages can use the
value property of a
PresentationAvailability object to offer presentation
only when there are available displays. However, the user
agent may not support continuous availability monitoring in the
background; for example, because of platform or power consumption
restrictions. In this case the Promise returned by
getAvailability() is
rejected, and the algorithm to monitor
the list of available presentation displays will only run as
part of the select a presentation display algorithm.
When the set of presentation availability objects is empty
(that is, there are no availabilityUrls being
monitored), user agents SHOULD NOT monitor the list of available
presentation displays to satisfy the
power saving non-functional requirement. To further save power,
the user agent MAY also keep track of whether a page holding
a PresentationAvailability object is in the
foreground. Using this information, implementation specific
discovery of presentation displays can be resumed or
suspended.
When the getAvailability() method is
called, the user agent MUST run the following steps:
PresentationRequest object that received the call to
getAvailability
presentationRequest, return that Promise and
abort these steps.
null, then:
If the set of presentation availability objects is non-empty, or there is a pending request to select a presentation display, the user agent MUST monitor the list of available presentation displays by running the following steps:
null, then
run the following substeps:
false.
true.
When a presentation display availability object is eligible for garbage collection, the user agent SHOULD run the following steps:
PresentationConnectionAvailableEvent
[Constructor(DOMString type, PresentationConnectionAvailableEventInit eventInitDict)]
interface PresentationConnectionAvailableEvent : Event {
[SameObject] readonly attribute PresentationConnection connection;
};
dictionary PresentationConnectionAvailableEventInit : EventInit {
required PresentationConnection connection;
};
A controlling user agent fires a trusted event
named connectionavailable on a
PresentationRequest when a connection associated with the
object is created. It is fired at the PresentationRequest
instance, using the PresentationConnectionAvailableEvent
interface, with the connection attribute set
to the PresentationConnection object that was
created. The event is fired for each connection that is created for
the controller, either by the controller calling
start() or reconnect(), or by the
controlling user agent creating a connection on the
controller's behalf via defaultRequest.
A receiving user agent fires a trusted event
named connectionavailable
on a PresentationReceiver when an incoming connection is
created. It is fired at the presentation controllers
monitor, using the PresentationConnectionAvailableEvent
interface, with the connection attribute set
to the PresentationConnection object that was
created. The event is fired for all connections that are created
when monitoring incoming presentation connections.
PresentationConnection
Each presentation connection is represented by a PresentationConnection object. Both the controlling user agent and receiving user agent MUST implement PresentationConnection.
enum PresentationConnectionState { "connecting", "connected", "closed", "terminated" };
enum BinaryType { "blob", "arraybuffer" };
interface PresentationConnection : EventTarget {
readonly attribute USVString id;
readonly attribute USVString url;
readonly attribute PresentationConnectionState state;
void close();
void terminate();
attribute EventHandler onconnect;
attribute EventHandler onclose;
attribute EventHandler onterminate;
// Communication
attribute BinaryType binaryType;
attribute EventHandler onmessage;
void send (DOMString message);
void send (Blob data);
void send (ArrayBuffer data);
void send (ArrayBufferView data);
};
The id attribute specifies the
presentation connection's presentation identifier.
The url attribute specifies the
presentation connection's presentation URL.
The state attribute represents the
presentation connection's current state. It can take one of
the values of PresentationConnectionState depending on the
connection state:
reconnect(). No communication is
possible.
When the close() method is called on a
PresentationConnection S, the user agent
MUST start closing the presentation connection S
with closed as
closeReason and an empty message as
closeMessage.
When the terminate() method is called on a
PresentationConnection S in a controlling
browsing context, the user agent MUST run the algorithm
to terminate a presentation in a controlling browsing
context using S.
When the terminate() method is called on a
PresentationConnection S in a receiving
browsing context, the user agent MUST run the algorithm
to terminate a presentation in a receiving browsing context
using S.
When a PresentationConnection object is created, its binaryType IDL 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 IDL attribute to the new value.
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.
When the send() method is called on a
PresentationConnection S, the user agent
MUST run the algorithm to send a message through
S.
When a PresentationConnection object S is discarded (because the document owning it is navigating or is closed) while the presentation connection state of S is connecting or connected, the user agent SHOULD start closing the presentation connection S with wentaway as closeReason and an empty closeMessage.
If the user agent receives a signal from the destination browsing context that a PresentationConnection S is to be closed, it SHOULD close the presentation connection S with closed or wentaway as closeReason and an empty closeMessage.
When the user agent is to establish a presentation connection using a presentation connection, it MUST run the following steps:
PresentationConnection object that is to be
connected
DOMString payloads in a reliable and in-order
fashion as described in the Send a Message and Receive a
Message steps below.
PresentationConnection
send() it has to be ensured
that messages are delivered to the other end reliably and in
sequence. The transport should function equivalently to an
RTCDataChannel in reliable mode.
Let presentation message data be the payload data to be
transmitted between two browsing contexts. Let presentation
message type be the type of that data, one of
text or binary.
When the user agent is to send a message through a presentation connection, it MUST run the following steps:
InvalidStateError exception.
binary if messageOrData is of type
ArrayBuffer, ArrayBufferView, or
Blob. Let messageType be text
if messageOrData is of type DOMString.
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.
Unable to send binary message (invalid_message)
for ArrayBuffer, ArrayBufferView and
Blob messages.
PresentationConnection
When the user agent has received a transmission from the
remote side consisting of presentation message data and
presentation message type, it MUST run the following steps
to receive a message through
a PresentationConnection:
MessageEvent interface, with the event
type message, which does not bubble, is not cancelable, and
has no default action.
text, then
initialize event's data attribute to
messageData with type DOMString.
binary, and
binaryType attribute is set to "blob", then initialize event's
data attribute to a new Blob object
with messageData as its raw data.
binary, and
binaryType attribute is set to "arraybuffer", then initialize
event's data attribute to a new
ArrayBuffer object whose contents are
messageData.
If the user agent encounters an unrecoverable error while receiving a message through presentationConnection, it SHOULD abruptly close the presentation connection presentationConnection with error as closeReason, and a human readable description of the error encountered as closeMessage.
PresentationConnectionCloseEvent
enum PresentationConnectionClosedReason { "error", "closed", "wentaway" };
[Constructor(DOMString type, PresentationConnectionCloseEventInit eventInitDict)]
interface PresentationConnectionCloseEvent : Event {
readonly attribute PresentationConnectionClosedReason reason;
readonly attribute DOMString message;
};
dictionary PresentationConnectionCloseEventInit : EventInit {
required PresentationConnectionClosedReason reason;
DOMString message = "";
};
A PresentationConnectionCloseEvent is fired when a
presentation connection enters a closed state. The
reason attribute provides the reason why the
connection was closed:
PresentationConnection called
close().
When the reason attribute is error, the user agent
SHOULD set the error message to a human readable description of how
the communication channel encountered an error.
PresentationConnection
When the user agent is to start closing a presentation connection, it MUST do the following:
PresentationConnection, passing the
closeReason to that context. The user agent does not
need to wait for acknowledgement that the corresponding
PresentationConnection was actually closed before
proceeding to the next step.
When the user agent is to close a presentation connection, it MUST do the following:
When a controlling user agent is to terminate a presentation in a controlling browsing context using connection, it MUST run the following steps:
When any of the following occur, the receiving user agent MUST terminate a presentation in a receiving browsing context:
window.close() in the
top-level browsing context or to a request to
navigate that context to a new resource.
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 that have no PresentationConnection objects whose presentation connection state is in the connected state after 30 minutes.
When a receiving user agent is to terminate a presentation in a receiving browsing context, it MUST run the following steps:
Only one termination confirmation needs to be sent per controlling user agent.
When a receiving user agent is to send a termination confirmation for a presentation P, and that confirmation was received by a controlling user agent, the controlling user agent SHOULD run the following steps:
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:
| Event handler | Event handler event type |
|---|---|
onmessage
|
message
|
onconnect
|
connect
|
onclose
|
close
|
onterminate
|
terminate
|
PresentationReceiver
interface PresentationReceiver {
[SameObject] readonly attribute Promise<PresentationConnectionList> connectionList;
};
The PresentationReceiver interface allows a receiving browsing context to access the controlling browsing contexts and communicate with them. The PresentationReceiver interface MUST be implemented in a receiving browsing context provided by a receiving user agent.
On getting, the connectionList attribute MUST return the result of running the following steps:
null, return the presentation controllers promise
and abort all remaining steps.
null, resolve the presentation controllers
promise with the presentation controllers monitor.
When the user agent is to create a receiving browsing context, it MUST run the following steps:
"denied".
Window clients and worker clients associated with the receiving browsing context and the other browsing context must not be exposed to service workers associated with each other.
When the receiving browsing context is closed, any associated service workers MUST be unregistered and terminated, and any associated browsing state, including session history, the cookie store, any HTTP authentication state, the application cache, any databases, the session storage areas, the local storage areas, the list of registered service worker registrations and the caches MUST be discarded and not used for any other receiving browsing context.
This algorithm is intended to create a well defined environment to allow interoperable behavior for 1-UA and 2-UA presentations.
The receiving user agent SHOULD fetch resources in a receiving browsing context with an HTTP Accept-Language header that reflects the language preferences of the controlling user agent (i.e., with the same Accept-Language that the controlling user agent would have sent). This will help the receiving user agent render the presentation with fonts and locale-specific attributes that reflect the user's preferences.
Given the operating context of the presentation display, some APIs will not work by design (for example, by requiring user input) or will be obsolete (for example, by attempting window management); the receiving user agent should be aware of this. Furthermore, any modal user interface will need to be handled carefully.
PresentationConnectionList
interface PresentationConnectionList : EventTarget {
readonly attribute FrozenArray<PresentationConnection> connections;
attribute EventHandler onconnectionavailable;
};
The connections attribute MUST return the non-terminated set of presentation connections in the set of presentation controllers.
When the receiving user agent is to start monitoring incoming presentation connections in a receiving browsing context from controlling browsing contexts, it MUST listen to and accept incoming connection requests from a controlling browsing context using an implementation specific mechanism. When a new connection request is received from a controlling browsing context, the receiving user agent MUST run the following steps:
null, run the following steps in parallel.
null, resolve the presentation
controllers promise with the presentation controllers
monitor.
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
|
allow-presentation keyword
This specification adds a new token, allow-presentation,
to the set of tokens allowed in the sandbox attribute of
an iframe. It adds a corresponding new flag to the
sandboxing flag set:
It amends the parse a sandboxing directive algorithm by adding an item to step 3:
allow-presentation
keyword.
The change event fired on the
PresentationAvailability object reveals one bit of information
about the presence (or non-presence) of a presentation display
typically discovered through the 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.
The API enables monitoring the list of available presentation displays. How the user agent determines the compatibility and availability of a presentation display with a given URL is an implementation detail. If a controlling user agent matches a presentation request URL to a DIAL application to determine its availability, this feature can be used to probe information about which DIAL applications the user has installed on the presentation display without user consent.
A presentation is allowed to be accessed across origins; the presentation URL and presentation ID used to create the presentation are the only information needed to reconnect to a connection from any origin in that user agent. In other words, a presentation is not tied to a particular opening origin.
This design allows controlling contexts from different domains to connect to a shared presentation resource. The security of the presentation ID prevents arbitrary pages from connecting to an existing presentation.
This specification allows a user agent to publish information about
its set of controlled presentations, and allows a browsing
context on another user agent to connect to a running presentation
via reconnect(). To
connect, the additional browsing context must discover the
presentation URL and presentation ID of the presentation, either
provided by the user, or via a shared service.
However, this specification makes no guarantee as to the identity of
the connecting party. Once connected, the receiving application may
wish to further verify the identity of the connecting party through
application-specific means. For example, the connecting application
could provide a token via send() that the receiving
application could verify corresponds an authorized entity.
When the user is asked permission to use a presentation display during the steps to select a presentation display, the controlling user agent should make it clear what origin is requesting presentation and what origin will be presented.
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.
Showing the origin that will be presented will help the user know
if that content is from an potentially secure (e.g.,
https:) origin, and corresponds to a known or
expected site. For example, a malicious site may attempt to
convince the user to enter login credentials into a presentation
page that imitates a legitimate site. Examination of the
requested origin will help the user detect these cases.
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.
In addition, it may be the case that the receiving user agent is capable of receiving user input, as well as acting as a presentation display. In this case, the receiving user agent should notify its user via browser chrome when a receiving browsing context is under the control of a remote party (i.e., it has one or more connected controllers).
The presentation API abstracts away what "local" means for displays, meaning that it exposes network-accessible displays as though they were local displays. 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.
The presentation URL and presentation ID 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.
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."
When in private browsing mode ("incognito"), the initial set of controlled presentations in that browsing session must be empty. Any presentation connections added to it must be discarded when the session terminates.
This spec will not mandate communication protocols between the controlling browsing context and the receiving browsing context, but it should set some guarantees of message confidentiality and authenticity between corresponding presentation connections.
Thanks to Addison Phillips, Anne Van Kesteren, Anssi Kostiainen, Anton Vayvod, Chris Needham, Christine Runnegar, Daniel Davis, Domenic Denicola, Erik Wilde, François Daoust, 闵洪波 (Hongbo Min), Hongki CHA, Hubert Sablonnière, Hyojin Song, Hyun June Kim, Jean-Claude Dufourd, Joanmarie Diggs, Jonas Sicking, Louay Bassbouss, Mark Watson, Martin Dürst, Matt Hammond, Mike West, Mounir Lamouri, Nick Doty, Oleg Beletski, Philip Jägenstedt, Richard Ishida, Shih-Chiang Chien, Takeshi Kanai, Tobie Langel, Tomoyuki Shimizu, Travis Leithead, and Wayne Carr for help with editing, reviews and feedback to this draft.
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 receiving user agent conformance class must include at least one implementation of the 1-UA mode and one implementation of the 2-UA mode.
For the purposes of these criteria, we define the following terms: