W3C Candidate Recommendation Draft
Copyright © 2024 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
This specification defines an API to enable Web content to access presentation displays and use them for presenting Web content.
This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Second Screen Working Group as a Candidate Recommendation Draft using the Recommendation track.
Since publication as Candidate Recommendation on 01 June
2017, the Working Group updated the steps to construct a
PresentationRequest
to ignore a URL with an unsupported
scheme, placed further restrictions on how receiving browsing contexts
are allowed to navigate themselves, and dropped the definition of the
BinaryType
enum in favor of the one defined in the HTML
specification. Other interfaces defined in this document did not change
other than to adjust to WebIDL updates. Various clarifications and
editorial updates were also made. See the list of changes for details.
No feature has been identified as being at risk.
The Second Screen Working Group will refine 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 Candidate Recommendation exit criteria section.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Draft integrates changes from the previous Candidate Recommendation that the Working Group intends to include in a subsequent Candidate Recommendation Snapshot.
This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 03 November 2023 W3C Process Document.
This section is non-normative.
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.
This section is non-normative.
Use cases and requirements are captured in a separate Presentation API Use Cases and Requirements document.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, OPTIONAL, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
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 mode 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 JavaScript
realm and current
realm are used as defined in [ECMASCRIPT]. The terms
resolved and rejected in the
context of Promise
objects are used as defined in [ECMASCRIPT].
The terms Accept-Language and HTTP authentication are used as defined in [RFC9110].
The term cookie store is used as defined in [RFC6265].
The term UUID is used as defined in [RFC4122].
The term DIAL is used as defined in [DIAL].
The term reload a document refers to steps run when the
reload
()
method gets called in [HTML].
The term local storage area refers to the storage areas
exposed by the localStorage
attribute, and the
term session storage area refers to the storage areas
exposed by the sessionStorage
attribute in
[HTML].
This specification references terms exported by other specifications, see B.2 Terms defined by reference. It also references the following internal concepts from other specifications:
This section is non-normative.
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.
This code renders a button that is visible when there is at least one
compatible presentation display that can present
https://example.com/presentation.html
or
https://example.net/alternate.html
.
Monitoring of display availability is done by first creating a
PresentationRequest
with the URLs you want to present, then
calling getAvailability
to
obtain a PresentationAvailability
object whose change
event will fire when presentation availability changes state.
<!-- 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>
When the user clicks presentBtn
, this code requests
presentation of one of the URLs in the PresentationRequest
.
When start
is called, the
browser typically shows a dialog that allows the user to select one
of the compatible displays that are available. The first URL in the
PresentationRequest
that is compatible with the chosen display
will be presented on that display.
The start
method resolves
with a PresentationConnection
object that is used to track the
state of the presentation, and exchange messages with the
presentation page once it's loaded on the display.
<!-- 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>
The presentation continues to run even after the original page that
started the presentation closes its PresentationConnection
,
navigates, or is closed. Another page can use the id
on the PresentationConnection
to reconnect to an existing presentation and resume control of it.
This is only guaranteed to work from the same browser that started
the presentation.
<!-- 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>
Some browsers have a way for users to start a presentation without
interacting directly with the controlling page. Controlling pages can
opt into this behavior by setting the defaultRequest
property on
navigator.presentation
, and listening for a
connectionavailable
event that is fired when a presentation is
started this way. The PresentationConnection
passed with the
event behaves the same as if the page had called start
.
<!-- 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>
Once a presentation has started, the returned
PresentationConnection
is used to monitor its state and
exchange messages with it. Typically the user will be given the
choice to disconnect from or terminate the presentation from the
controlling page.
Since the the controlling page may connect to and disconnect from
multiple presentations during its lifetime, it's helpful to keep
track of the current PresentationConnection
and its state.
Messages can only be sent and received on connections in a
connected
state.
<!-- 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.onclose = 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>
This code runs on the presented page
(https://example.org/presentation.html
). Presentations
may be connected to from multiple controlling pages, so it's
important that the presented page listen for incoming connections on
the connectionList
object.
<!-- presentation.html -->
<script>
var addConnection = function(connection) {
connection.onmessage = function (message) {
if (message.data == "Say hello")
connection.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.body.appendChild(spanElt);
};
</script>
It's possible for a controlling page to start and control two independent presentations on two different presentation displays. This code shows how a second presentation can be added to the first one in the examples above.
<!-- controller.html -->
<!-- The same controlling page can create and manage multiple presentations,
by calling start() multiple times. -->
<button id="secondPresentBtn" style="display: none;">Present Again</button>
<script>
var secondPresentBtn = document.getElementById("secondPresentBtn");
var secondPresUrl = "https://example.com/second-presentation.html";
var secondRequest = new PresentationRequest(secondPresUrl);
// For simplicity, the logic to handle screen availability for secondRequest
// and update the status of secondPresentBtn is omitted.
secondPresentBtn.onclick = function () {
// Start new presentation, likely on a different screen than the original
// request.
secondRequest.start().then(setSecondConnection);
};
function setSecondConnection(newConnection) {
// Logic to handle messages to/from second-presentation.html.
};
</script>
A presentation display refers to a graphical and/or audio output device 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 presentation URL if the controlling user agent can reasonably guarantee that 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. In algorithms
for PresentationRequest
, the controlling browsing
context is the browsing context whose JavaScript
realm was used to construct the PresentationRequest
.
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.
When an algorithm queues a Presentation API task T, the user agent MUST queue a global task T on the presentation task source using the global object of the current realm.
Unless otherwise specified, the JavaScript realm for script objects constructed by algorithm steps is the current realm.
WebIDL
[SecureContext, Exposed=Window]
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:
WebIDLpartial 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:
WebIDLpartial 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 (including child navigables of the receiving browsing
context) it MUST return null
.
Web developers can use navigator.presentation.receiver to detect when a document is loaded as a presentation.
WebIDL[SecureContext, Exposed=Window]
interface PresentationRequest
: EventTarget {
constructor
(USVString url);
constructor
(sequence<USVString> urls);
Promise<PresentationConnection
> start
();
Promise<PresentationConnection
> reconnect
(USVString presentationId);
Promise<PresentationAvailability
> getAvailability
();
};
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
SecurityError
and abort these steps.
NotSupportedError
and abort all remaining
steps.
SyntaxError
exception and abort all
remaining steps.
NotSupportedError
and abort all remaining steps.
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
Promise
Promise
rejected with an
InvalidAccessError
exception and abort these steps.
Promise
from a previous
call to start
in
topContext or any browsing context in the
descendant navigables of topContext, return
a new Promise
rejected with an OperationError
exception and
abort all remaining steps.
Promise
.
NotFoundError
exception.
NotAllowedError
exception, and abort all remaining steps.
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
Promise
that will be resolved with
a new presentation connection
PresentationConnection
S.
connecting
.
connectionavailable
,
that uses the PresentationConnectionAvailableEvent
interface, with the connection
attribute
initialized to S, at presentationRequest.
The event must not bubble and must not be cancelable.
error
as
closeReason, and a human readable message describing
the failure as closeMessage.
http
or https
schemes; behavior for other schemes is not
defined by this specification.
When the reconnect
method is called, the user agent MUST run the following
steps to reconnect to a presentation:
PresentationRequest
object that reconnect
was called on
Promise
Promise
.
PresentationConnection
that meets the following criteria:
terminated
PresentationConnection
exists, run the
following steps:
PresentationConnection
.
connecting
or
connected
,
then abort all remaining steps.
connecting
.
PresentationConnection
that meets the following criteria:
terminated
PresentationConnection
exists, run the
following steps:
PresentationConnection
.
PresentationConnection
newConnection.
connecting
.
connectionavailable
, that uses the
PresentationConnectionAvailableEvent
interface, with
the connection
attribute initialized to newConnection, at
presentationRequest. The event must not bubble and
must not be cancelable.
NotFoundError
exception.
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
|
Each presentation connection is represented by a
PresentationConnection
object. Both the controlling user
agent and receiving user agent MUST implement
PresentationConnection
.
WebIDLenum PresentationConnectionState
{ "connecting
", "connected
", "closed
", "terminated
" };
[SecureContext, Exposed=Window]
interface PresentationConnection
: EventTarget {
readonly attribute USVString id
;
readonly attribute USVString url
;
readonly attribute PresentationConnectionState
state
;
undefined close
();
undefined terminate
();
attribute EventHandler onconnect
;
attribute EventHandler onclose
;
attribute EventHandler onterminate
;
// Communication
attribute BinaryType binaryType
;
attribute EventHandler onmessage
;
undefined send
(DOMString message);
undefined send
(Blob data);
undefined send
(ArrayBuffer data);
undefined 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:
connecting
means that the user agent is attempting to
establish a presentation connection with the
destination browsing context. This is the initial state
when a PresentationConnection
object is created.
connected
means that the presentation
connection is established and communication is possible.
closed
means that the presentation connection
has been closed, or could not be opened. It may be re-opened
through a call to reconnect
. No communication is
possible.
terminated
means that the receiving browsing
context has been terminated. Any presentation
connection to that presentation is also
terminated and cannot be re-opened. No communication is possible.
connected
state does not mean that sending or receiving messages will
succeed, as the communication channel may be abruptly closed at any
time. Applications that wish to detect such situations as soon as
possible should implement their own keep-alive mechanism.
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.
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.
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.
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
MUST 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 MUST 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
connecting
, then abort all
remaining steps.
connected
.
connect
at
presentationConnection.
error
as
closeReason, and a human readable message describing the
failure as closeMessage.
DOMString
and binary 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:
state
property of
presentationConnection is not connected
, throw an
InvalidStateError
exception.
binary
if messageOrData is of type
ArrayBuffer
, ArrayBufferView
, or Blob
. Let
messageType be text
if
messageOrData is of type DOMString
.
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.
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
:
state
property of
presentationConnection is not connected
, abort these steps.
MessageEvent
interface, with the event type
message
, which does not bubble and is not cancelable.
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 MUST abruptly close the
presentation connection presentationConnection with
error
as
closeReason. It SHOULD use a human readable description
of the error encountered as closeMessage.
WebIDLenum PresentationConnectionCloseReason
{ "error
", "closed
", "wentaway
" };
[SecureContext, Exposed=Window]
interface PresentationConnectionCloseEvent
: Event {
constructor
(DOMString type, PresentationConnectionCloseEventInit
eventInitDict);
readonly attribute PresentationConnectionCloseReason
reason
;
readonly attribute DOMString message
;
};
dictionary PresentationConnectionCloseEventInit
: EventInit {
required PresentationConnectionCloseReason
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. It can
take one of the values of
PresentationConnectionCloseReason
:
error
means that the mechanism for connecting or
communicating with a presentation entered an unrecoverable error.
closed
means that either the controlling browsing
context or the receiving browsing context that were
connected by the PresentationConnection
called
close()
.
wentaway
means that the browser closed the connection,
for example, because the browsing context that owned the
connection navigated or was discarded.
When the reason
attribute is
error
, the
user agent SHOULD set the message
attribute to a
human readable description of how the communication channel
encountered an error.
When the PresentationConnectionCloseEvent
constructor is
called, the user agent MUST construct a new
PresentationConnectionCloseEvent
object, with its
reason
attribute set to the reason
member of the
PresentationConnectionCloseEventInit
object passed to
the constructor, and its message
attribute set to the
message
member of this
PresentationConnectionCloseEventInit
object if set, to an
empty string otherwise.
PresentationConnection
When the user agent is to start closing a presentation connection, it MUST do the following:
PresentationConnectionCloseReason
describing why the
connection is to be closed
connecting
or connected
then abort the
remaining steps.
closed
.
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.
wentaway
, then locally run
the steps to close the presentation connection with
presentationConnection, closeReason, and
closeMessage.
When the user agent is to close a presentation connection, it MUST do the following:
PresentationConnectionCloseReason
describing why the
connection is to be closed
connecting
,
connected
,
or closed
,
then abort the remaining steps.
closed
, set it to
closed
.
close
, that uses the
PresentationConnectionCloseEvent
interface, with the
reason
attribute initialized to closeReason and the
message
attribute initialized to closeMessage, at
presentationConnection. The event must not bubble
and must not be cancelable.
When a controlling user agent is to terminate a presentation in a controlling browsing context using connection, it MUST run the following steps:
connected
or connecting
, then abort these
steps.
connected
or
connecting
,
then queue a global task on the presentation task
source given known connection's relevant
global object to run the following steps:
terminated
.
terminate
at
known connection.
When any of the following occur, the receiving user agent MUST terminate a presentation in a receiving browsing context:
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.
When a receiving user agent is to terminate a presentation in a receiving browsing context, it MUST run the following steps:
connected
, then add
connection to connectedControllers.
terminated
.
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 MUST run the following steps:
connected
or
connecting
,
then abort the following steps.
terminated
.
terminate
at
connection.
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
|
WebIDL[SecureContext, Exposed=Window]
interface PresentationReceiver
{
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.
Promise
constructed in the JavaScript realm of this
PresentationReceiver
object.
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"
.
Cache
objects for C.
All child navigables created by the presented document, i.e. that have the receiving browsing context as their top-level browsing context, MUST also have restrictions 2-4 above. In addition, they MUST have the sandboxed top-level navigation without user activation browsing context flag set. All of these browsing contexts MUST also share the same browsing state (storage) for features 5-10 listed above.
When the top-level browsing context attempts to navigate to a new resource and runs the steps to navigate, it MUST follow step 1 to determine if it is allowed to navigate. In addition, it MUST NOT be allowed to navigate itself to a new resource, except by navigating to a fragment identifier or by reloading its document.
This allows the user to grant permission based on the origin of the presentation URL shown when selecting a presentation display.
If the top-level-browsing context was not allowed to navigate, it SHOULD NOT offer to open the resource in a new top-level browsing context, but otherwise SHOULD be consistent with the steps to navigate.
Window clients and worker clients associated with the receiving browsing context and its descendant navigables must not be exposed to service workers associated with each other.
When the receiving browsing context is terminated, any
service workers associated with it and the browsing
contexts in its descendant navigables MUST be
unregistered and terminated. Any browsing state associated with the
receiving browsing context and the browsing contexts
in its descendant navigables, including session
history, the cookie store, any HTTP
authentication state, any databases, the session
storage areas, the local storage areas, the list of
registered service worker registrations and the Cache
objects MUST be discarded and not used for any other browsing
context.
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.
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 Web 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. The sandboxed modals flag is set on the receiving browsing context to prevent most of these operations.
As noted in Conformance, a user agent that is both a controlling user agent and receiving user agent may allow a receiving browsing context to create additional presentations (thus becoming a controlling browsing context as well). Web developers can use navigator.presentation.receiver to detect when a document is loaded as a receiving browsing context.
WebIDL[SecureContext, Exposed=Window]
interface PresentationConnectionList
: EventTarget {
readonly attribute FrozenArray<PresentationConnection
> connections
;
};
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:
PresentationConnection
S.
connected
.
Otherwise, set the presentation connection state of
S to closed
and abort all remaining
steps.
null
, run the following steps in parallel.
PresentationConnectionList
constructed in the
JavaScript realm of the PresentationReceiver
object of the receiving browsing context.
null
, queue a Presentation API task to
resolve the presentation controllers promise with
the presentation controllers monitor.
connectionavailable
, that
uses the PresentationConnectionAvailableEvent
interface, with the connection
attribute initialized to S, at the presentation
controllers monitor. The event must not bubble and must
not be cancelable.
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
|
This section is non-normative.
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.
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 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 also allows a receiving user agent to
publish information about its set of controlled presentations,
and a controlling user agent to reconnect to presentations
started from other devices. This is possible when the controlling
browsing context obtains the presentation URL and
presentation identifier of a running presentation from the
user, local storage, or a server, and then connects to the
presentation via reconnect
.
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.
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 child navigable. For example, embedded content may try to convince the user to click to trigger a request to start an unwanted presentation.
The sandboxed top-level navigation without user activation browsing context flag is set on the receiving browsing context to enforce that the top-level origin of the presentation remains the same during the lifetime of the 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.
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 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.
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.
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, they 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.
WebIDLpartial interface Navigator {
[SecureContext, SameObject] readonly attribute Presentation
presentation
;
};
[SecureContext, Exposed=Window]
interface Presentation
{
};
partial interface Presentation
{
attribute PresentationRequest
? defaultRequest
;
};
partial interface Presentation
{
readonly attribute PresentationReceiver
? receiver
;
};
[SecureContext, Exposed=Window]
interface PresentationRequest
: EventTarget {
constructor
(USVString url);
constructor
(sequence<USVString> urls);
Promise<PresentationConnection
> start
();
Promise<PresentationConnection
> reconnect
(USVString presentationId);
Promise<PresentationAvailability
> getAvailability
();
attribute EventHandler onconnectionavailable
;
};
[SecureContext, Exposed=Window]
interface PresentationAvailability
: EventTarget {
readonly attribute boolean value
;
attribute EventHandler onchange
;
};
[SecureContext, Exposed=Window]
interface PresentationConnectionAvailableEvent
: Event {
constructor
(DOMString type, PresentationConnectionAvailableEventInit
eventInitDict);
[SameObject] readonly attribute PresentationConnection
connection
;
};
dictionary PresentationConnectionAvailableEventInit
: EventInit {
required PresentationConnection
connection
;
};
enum PresentationConnectionState
{ "connecting
", "connected
", "closed
", "terminated
" };
[SecureContext, Exposed=Window]
interface PresentationConnection
: EventTarget {
readonly attribute USVString id
;
readonly attribute USVString url
;
readonly attribute PresentationConnectionState
state
;
undefined close
();
undefined terminate
();
attribute EventHandler onconnect
;
attribute EventHandler onclose
;
attribute EventHandler onterminate
;
// Communication
attribute BinaryType binaryType
;
attribute EventHandler onmessage
;
undefined send
(DOMString message);
undefined send
(Blob data);
undefined send
(ArrayBuffer data);
undefined send
(ArrayBufferView data);
};
enum PresentationConnectionCloseReason
{ "error
", "closed
", "wentaway
" };
[SecureContext, Exposed=Window]
interface PresentationConnectionCloseEvent
: Event {
constructor
(DOMString type, PresentationConnectionCloseEventInit
eventInitDict);
readonly attribute PresentationConnectionCloseReason
reason
;
readonly attribute DOMString message
;
};
dictionary PresentationConnectionCloseEventInit
: EventInit {
required PresentationConnectionCloseReason
reason
;
DOMString message
= "";
};
[SecureContext, Exposed=Window]
interface PresentationReceiver
{
readonly attribute Promise<PresentationConnectionList
> connectionList
;
};
[SecureContext, Exposed=Window]
interface PresentationConnectionList
: EventTarget {
readonly attribute FrozenArray<PresentationConnection
> connections
;
attribute EventHandler onconnectionavailable
;
};
binaryType
attribute for PresentationConnection
§6.5close
method for PresentationConnection
§6.5"connected"
enum value for PresentationConnectionState
§6.5"connecting"
enum value for PresentationConnectionState
§6.5connectionList
attribute for PresentationReceiver
§6.6connections
attribute for PresentationConnectionList
§6.7defaultRequest
attribute for Presentation
§6.2.1"error"
enum value for PresentationConnectionCloseReason
§6.5.4getAvailability
method for PresentationRequest
§6.4.3id
attribute for PresentationConnection
§6.5onchange
attribute for PresentationAvailability
§6.4onclose
attribute for PresentationConnection
§6.5.9onconnect
attribute for PresentationConnection
§6.5.9onmessage
attribute for PresentationConnection
§6.5.9onterminate
attribute for PresentationConnection
§6.5.9presentation
attribute for Navigator
§6.2Presentation
interface
§6.2PresentationAvailability
interface
§6.4PresentationConnection
interface
§6.5PresentationConnectionAvailableEvent
interface
§6.4.5PresentationConnectionAvailableEventInit
dictionary
§6.4.5PresentationConnectionCloseEvent
interface
§6.5.4PresentationConnectionCloseEventInit
dictionary
§6.5.4PresentationConnectionCloseReason
enum
§6.5.4PresentationConnectionList
interface
§6.7PresentationConnectionState
enum
§6.5PresentationReceiver
interface
§6.6PresentationRequest
interface
§6.3receiver
attribute for Presentation
§6.2.2reconnect
method for PresentationRequest
§6.3.5send
method for PresentationConnection
§6.5start
method for PresentationRequest
§6.3.2state
attribute for PresentationConnection
§6.5terminate
method for PresentationConnection
§6.5"terminated"
enum value for PresentationConnectionState
§6.5url
attribute for PresentationConnection
§6.5value
attribute for PresentationAvailability
§6.4"wentaway"
enum value for PresentationConnectionCloseReason
§6.5.4Event
interface
EventInit
EventTarget
interface
Blob
interface
Document
)
EventHandler
localStorage
attribute (for WindowLocalStorage
)
MessageEvent
interface
reload()
(for Location
)
sessionStorage
attribute (for WindowSessionStorage
)
Cache
interface
ArrayBuffer
interface
ArrayBufferView
boolean
type
DOMString
interface
[Exposed]
extended attribute
FrozenArray
interface
InvalidAccessError
exception
InvalidStateError
exception
NotAllowedError
exception
NotFoundError
exception
NotSupportedError
exception
OperationError
exception
Promise
interface
[SameObject]
extended attribute
[SecureContext]
extended attribute
SecurityError
exception
SyntaxError
exception
exception
)
undefined
type
USVString
interface
RTCDataChannel
interface
BinaryType
enum
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.
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.
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:
This section is non-normative.
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.
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in:
Referenced in: