Presentation API
Home Page: https://www.w3.org/TR/presentation-api/
License: Other
This repository contains the Presentation API specification that is being worked on in the W3C Second Screen Working Group.
Please refer to the group's Work Mode for instructions on how to contribute.
The Presentation API attempts to address the use cases and requirements outlined in the specification at: http://w3c.github.io/presentation-api/#use-cases-and-requirements-0
We should evaluate the UCs and Reqs we laid out initially, and based on group discussion and consensus see if changes are needed. For example, people working on the implementations may have discovered new requirements that we did not anticipate initially that would be in scope for the group. I propose we discuss this at F2F time permitting, and to make for a productive session, more complete proposals for new use cases and requirements should be provided before the meeting.
From http://webscreens.github.io/presentation-api/#open-questions:
Do we need an additional state like resumed in order to identify resumed session? It seems that this could be handled on the page level. The opener page could ask the presentation page whether it is "new" or "resumed".
From http://lists.w3.org/Archives/Public/public-webscreens/2014Aug/0003.html and replies:
Proposed is a mechanism for reconnecting to existing presentations, either when the controlling page navigates, or a page is notified of the existence of a presentation via some out-of-band means (cookies, a server, etc.).
One option considered:
partial interface NavigatorPresentation : EventTarget {
PresentationSession requestSession(DOMString url,
optional DOMString presentationId,
optional boolean onlyReconnect);
}
This would reconnect to the presentation identified by the url and presentationId; if onlyReconnect is set to 'true', the user would not be prompted to start a new presentation with those parameters.
Another option:
partial interface NavigatorPresentation {
PresentationSession startSession(DOMString url, DOMString sessionId);
PresentationSession joinSession(DOMString url, DOMString sessionId);
}
Which makes the choice of starting vs. reconnecting more explicit.
[email protected] writes:
"Also, what do the function(s) return if the session is not established (e.g. user exits the selection UI by dismissing the popup menu or there's no existing session to join) ? An uninitialized useless session object? Or should we change the return type to a Promise that passes a session to the caller if it succeeds?"
The assumption thus far is that the user agent is the only entity that can determine what screens are available for presentation. However, some sites will be able to access screens entirely based on interaction over the Internet, i.e. using XHR or WebSockets to a server, or perhaps WebRTC. Ideally these should be offered to the user as presentation targets alongside browser-discovered screens, so that the site author doesn't have to offer two distinct presentation mechanisms.
Considerations:
I think this is a useful enhancement that would allow innovation and extension over browser-provided presentation capabilities.
A user may have more than one second screen available and an application may want to take advantage of all these screens at once. However, as things stand, such an application:
startSession a second timeImprove the screenavailable mechanism so that the flag reflects the presence of unused second screens at any time?
See initial discussion in https://lists.w3.org/Archives/Public/public-secondscreen/2015Jan/0012.html
See also #1 (multi-display support) and #39 (resumption of multiple sessions)
An implication of reconnection is that multiple pages may connect to the same presentation. The behavior of the API should be defined for this scenario. Specifically,
onstatechange = "connected"/"disconnected" on both sidesclose() on both sidesThe current spec considers only one connected display. From my point of view I think it is better to support multiple displays that can be connected to the same Browser. Example: Presentation with slides view on one screen and notes view on another screen and mobile device as input device.
Presumably the user agent will provide the ability for the browser with the initiating page to close the presented document (local or remote). However we may want the user agent to close it on the user's behalf when:
(1) There are no controlling sessions connected for some period of time (e.g., idle timeout)
(2) The presentation is being rendered locally (1-UA) and the media stream has has been terminated permanently.
(3) The presentation is being rendered locally and the user wishes to exit the user-agent.
(4) The presentation wishes to terminate itself.
Some of these scenarios can be implemented by the app developer; if so the behavior of e.g. window.close() should be defined in the presentation context.
If we allow the page to filter the set of presentation screens based on capabilities, then more bits of more information would be revealed. This feature, if implemented, should take privacy into consideration.
It is an open issue whether to provide filter information as part of the request for notification of available screens. This could be useful when a particular application or capability is needed in order to display the contents of a presentation. One possible approach to this could be to provide the URL for the presentation and / or required options as part of the request for notification of available screens. If this was supported, only screens that satisfied the filter would trigger a notification.
The "Status of This Document" section should be updated before we publish FPWD:
http://w3c.github.io/presentation-api/#sotd
IIRC @tidoust volunteered to take this.
Hi, all.
I would like to make some minor editorial changes on our document.
I see two very simliar looking files at the master directory: index.html & Overview.src.html
Could anybody tell me the difference between these two?
To be more precise,
Why do we need the spec source (Overview.src.html) and the generated spec (index.html) separately?
Thanks in advance!
The algorithms for startSession and joinSession indicate that specific error types like PermissionDenied and NoPresentationFound should be used when rejecting the Promises returned to the caller. However @avayvod has pointed out these types are not part of the DOMException list for WebIDL.
If we wish to use these types we should define our own PresentationError object with Presentation-API specific error types.
Alternatively, we could try to re-use existing DOMException types, which seems to be done in other specs (Push API, Service Workers API).
Also see:
From http://webscreens.github.io/presentation-api/#example:
Do we want to fire an event immediately after the page registers for it? What's a best practice method for asynchronous notifications of ths kind?
Via http://lists.w3.org/Archives/Public/public-webscreens/2014Aug/0003.html
The specification does not define when the user agent rendering the presentation will be able to access the session across page navigation.
One proposal is to have the PresentationSession implement Transferable so it can be passed to and from a SharedWorker.
Another option would be for the presented page to reconnect to the session in a manner similar to the controlling page (see https://github.com/webscreens/presentation-api/issues/15).
A third option is for navigation to always terminate the presentation. This simplifies the API and gives the session a well defined lifetime, but may be limiting to some developers.
From http://lists.w3.org/Archives/Public/public-webscreens/2014Aug/0003.html and replies:
To support 2-UA usage the specification should define the data types that can be passed via the communication channel. These should be a subset (or identical to) the network serializable types allowed by the WebSocket and RTCDataChannel APIs.
Now that we moved to a working group, copyright and other legal information needs to be updated.
The spec should specify any restrictions on the presenting browsing context when the opening browsing context is in "incognito" mode.
From public-webscreens and related threads:
The specification should define the behavior of the following Web features for the presenting page across presentation sessions. The goals are the following:
The following Web features have been discussed (and there may be others to consider):
In some scenarios the presented page may have active connections to multiple PresentationSessions on other pages. In a gaming scenario, each connected session would represent a game player. Some information (like dealing a card into the hand) should be sent to one player, while other information (playing a card face up) should be sent to all players.
We need to specify:
(1) How the presented page may communicate to a specific connected page
(2) How the presented page may broadcast - communicate to all specific connected pages
If a page created two different sessions for the same URL and presentation ID on two different screens, how can it reconnect to both sessions?
The current algorithm for reconnecting sessions returns the session that was most recently connected to.
Should joinSession rather return an array of PresentationSession objects?
Should the page rather use different presentation IDs?
See initial discussion in https://lists.w3.org/Archives/Public/public-secondscreen/2015Jan/0012.html
public-secondscreen thread:
While discussing the Hbb 2.0 TV standard, the issue of how WebSockets would be used to communicate between the controlling Web application and the presenting TV Web application.
If these Web applications are provided on secure (https://) origins, some guarantees of message confidentiality and authenticity of either party should be made to meet the standards set out by the Mixed Content proposal.
This issue will be addressed by a spec change to spell out the security requirements for the messaging channel as part of the Security and Privacy sections of the spec.
From, e.g. http://lists.w3.org/Archives/Public/public-webscreens/2014May/0061.html and replies:
Requesting display of non HTML content
The second issue at stake is about specifying what happens when a call such as the following is issued:
navigator.presentation.requestShow('video.mp4');
The main problem is that, regardless of where this runs, this does not create a "browsing context" as such since a video is not an HTML document.
While it's easy to see how a browser could create a fake browsing context for the video (as is done in practice when you open a link to a video in your browser), it's hard to see how the initiating page can communicate with the created browsing context to control video playback.
The proposed solution would involve the
This issue tracks the work needed to specify this behavior.
Do we require that the opener and presenting page share an origin? Can we allow CORS?
As we make progress with the spec and the normative sections begin to be self-contained, we may want to carve out the now very extensive Requirements and Example sections into its own "Use Cases and Requirements (and Examples)" document we can evolve in tandem with the API specification at a later stage, referenced from the API spec. Perhaps leave one concise example in the spec.
From http://webscreens.github.io/presentation-api/#open-questions:
If there are already connected screens when the page subscribes to the onavailablechange event, we can handle this in two ways: We can synthesize one initial event to notify the page about available screens as soon as the first event handler is installed (as described). Or we can add another message like navigator.presentation.getAvailable(function(available) { } ); to notify the page about available screens using this one-time asynchronous getter. Which way should we go?
Also see: https://github.com/webscreens/presentation-api/issues/8
s.onstatechange is not an EventTarget. s is.
This is the meta issue to ensure we meet the W3C Process requirements for the First Public Working Draft publication.
Per the W3C Process [1], to publish the First Public Working Draft of a document, a Working Group must meet the applicable general requirements for advancement, enumerated below:
[email protected]:
Are multiple simultaneous calls permitted to startSession()? My intuition is "no", but I would like to ask the group if there are any use cases where this is necessary. If the answer is "yes" it adds some constraints and complexity to the user interface for screen selection in the browser. In particular if we return a Promise from startSession() then I am not sure how we would enforce one-at-a-time.
@tidoust noted that the newly updated W3C Document License [1](effective 1 February 2015) affects all publications, including specs that have already been published, so our spec will de facto adopt that updated license. The custom text defined in the WG's charter (that landed recently) has become redundant with the license.
TL;DR - we should update the license boilerplate again (sorry for the boilerplate churn).
Presentation API addresses currently presentation of hosted web content (e.g. accessible via http:// or https://). According to the spec, presentation URLs follows the URL Standard. Questions is: are there other relevant URL schemes for Presentation API? for example data: scheme can be used in the following way:
var presentationUrl = 'data:text/html,<!DOCTYPE html><html><body><p>Test</p><script>/* inline JavaScript that may use navigator.presentatoion.session */</script></body></html>';
var session = navigator.presentatoion.startSession(presentationUrl);Also the file:// protocol could be relevant for non-hosted web content for example for Packaged Web Application like W3C Widgets.
All relevant schemes need to be evaluated regarding limitations, security implications, performance etc. for usage in Presentation API. Also use cases to derive requirements are needed.
[Carved out into its own issue from https://github.com//issues/26#issuecomment-91708418]
@mfoltzgoogle says:
@avayvod In Chrome have been discussing how browser-initiated
presentation interacts with multiple <iframe>s embedded in the
controlling page. For now, we are only enabling browser-initiated
presentation from the default presentation URL set in the top level
document. However, there is a use case for allowing it from an
embedded <iframe> for sites using a third party player to show a
single piece of video (or other) content.
We have discussed possible solutions, including:
Instead we are considering adding a capability to the <iframe>'s
sandbox attribute, "allow-default-presentation", that would allow the
parent page to designate up to one iframe per document as the source
of the default presentation URL for browser initiated presentation.
This attribute would be respected only for <iframes> one level deep.
We should complete the Security and privacy considerations section to the Presentation API once we're better aware of the threats.
The spec has been evaluated against Self-Review Questionnaire: Security and Privacy, with results documented in this issue. Furthermore, the Privacy Interest Group (PING) has produced documentation that may be helpful, namely Fingerprinting Guidance for Web Specification Authors and Privacy Considerations for Web Protocols. The Web Security IG review and PING review of the specification have been initiated. This sections should be crafted based on feedback from the respective reviews.
We do not want to require user permission before disclosing the presence of a presentation display, as it is counter to the initial purpose of improving the user experience.
[email protected]:
Can the web developer make any assumptions about the dimensions of the viewport for rendering the presentation? For example must it be a minimum size, or must it match the aspect ratio of the display that is actually rendering the content? I believe the aspect ratio constraint is the most important, but I could also see that a minimum size would help Web authors with layout and CSS.
We should understand the constraints that a possible compatibility with HbbTV could put on the design of the Presentation API.
Related discussion at: https://lists.w3.org/Archives/Public/public-secondscreen/2015Feb/0102.html
The Presentation API distinguishes between the two sides of the equation: the opening browsing context and the presenting browsing context. The interfaces that user agents need to implement are different depending on which side you consider. Also, I think we envision user agents that can run an opening browsing context but cannot run a presenting browsing context, and conversely user agents that can run a presenting browsing context but cannot run an opening browsing context.
In spec parlance, this means that there exists (at least) two different classes of products that can claim conformance against the Presentation API specification. The specification should be explicit about this in the Conformance section and clearly identify the interfaces, algorithms and normative statements that apply to a given class of products.
This is somewhat different from most other JavaScript APIs that target a single user agent and thus can remain pretty laconic on the definition of classes of products. As a counter example, the HTML5 specification defines different classes of products, including Conforming documents, Web browsers and other interactive user agents and Conformance checkers [html5].
The definition of classes of products can remain pretty simple. As a starting point, I would suggest to reference the definitions of opening browsing context and presenting browsing context with wording in the Conformance section such as:
[[
This specification describes conformance criteria for two classes of products:
A user agent may act both as an opening user agent and as a presenting user agent, provided it implements all the required interfaces. This happens, e.g. when the opening user agent runs the presenting browsing context locally, or when the presenting user agent wants to allow a presenting browsing context to initiate or resume a presentation session on its own.
]]
We could also treat the 1UA case as a separate class of products but I am not yet clear whether we will need to define normative statements that will only apply to the presenting browsing context when it runs in the opening user agent.
Having clear classes of products is good practice (see relevant guideline in "QA Framework: Specification Guidelines" [qa]). It is useful to make conformance claims but note it also helps with testing (see "A Method for Writing Testable Conformance Requirements" [test]) and specification authoring (once you have clear classes of conformance, you will probably want to separate interfaces as suggested in #91 to make it easier for readers/developers).
Feel free to suggest better definitions. The main point in this issue is not the text in itself but the fact that the spec needs to define the conformance classes.
[html5] http://www.w3.org/TR/html5/infrastructure.html#conformance-classes
[test] http://www.w3.org/TR/test-methodology/
[qa] http://www.w3.org/TR/2005/REC-qaframe-spec-20050817/#what-conform
There are rough edges when it comes to closing the session, resuming it. We need to gain experience from implementations what happens, when the session is disconnected, user-closed, remote-end closed etc.
This section is one aspect of this, but probably the example section needs to shed more light on how expected and unexpected disconnects are handled.
Poker
Bob enters an online poker site on his smartphone to play poker with friends. He selects the option "
create new game" to start a game session for two players. The poker site detects that there is display available and asks Bob to extend the game UI by keeping his personal cards and control UI on the smartphone and displaying the poker table on the large display. Bob confirms and waits for other players to join. Alice is visiting Bob and decides to join the game. She opens the same poker site in the browser on her smartphone and selects the option "join game". The browser shows a dialog with a list of running poker sessions. She selects the session started by Bob and joins the game. The game starts immediately after two players are joined. Now Alice and Bob can see their personal cards on their smartphones and the large screen displays the poker table with shared cards, current bets, and remaining money of each player.
Poker Player View
Poker Table Screen
[Migrating the following inline issue from the spec into the issue tracker:]
The purpose of the session attribute is to provide the presented page with access to the PresentationSession without allowing a potential race condition between the registration of an event handler and the firing of an event, or complicating the browser implementation to fix this case. It should be null in an opening context and non-null in a presented document.
Pull request #77 added definitions to the spec for the default presentation URL and ID to allow the UA to initiate presentation on behalf of the page. This issue tracks an update to the algorithms for 6.4, "Interface NavigatorPresentation" to define the side effects on the UA state when this happens.
The current events-based API for availability monitoring relies on the following side-effect: adding/removing a listener for the availablechange event starts/stops discovery. This is discouraged (see the historical discussion [1], also implementability concerns [2]).
A promise-based API is proposed as the solution [2][3].
[1] https://lists.w3.org/Archives/Public/public-device-apis/2011Sep/0025.html
[2] https://lists.w3.org/Archives/Public/public-secondscreen/2015Apr/0079.html
[3] https://lists.w3.org/Archives/Public/public-secondscreen/2015Apr/0068.html
Enable a Web application to turn itself into a Presentation session so that it can be discovered by others. A possible technical solution would be to use a meta element.
For instance, to turn a Web application into a public Presentation Session:
<meta name="presentation" />
To turn a Web application into a private (or invitation-only) Presentation Session:
<meta name="presentation" content="[[presentationId]]" />
A user starts a Web application on her Smart TV from the usual TV remote that displays family pictures and videos in the background. While the application runs, her child opens the same application on his tablet, joins the running presentation application on the Smart TV and adds pictures and comments to the slideshow.
The Web application started on the Smart TV cannot advertise itself as a presentation session since it got started as a "regular" application.
Note it becomes possible as soon as the Web application on the Smart TV is started from another device using the Presentation API, but the goal is to avoid that step.
Not likely in the generic case.
The UA could propose a "start this application as a presentation session" menu item, but this is unlikely to serve any useful purpose in most of the cases as applications that will be able to be started as such will be exceptions-to-the-rule (at least for some time to come!).
The UA could perhaps detect whether the JavaScript of the application makes use of Presentation API interfaces before proposing that choice, but it's easy to use obfuscate code in JavaScript and hide the code to Presentation API interfaces.
In a packaged app environment, the application could also perhaps request to be run as a Presentation session in a manifest file.
The receiving UA must provide a means for a Web application to turn itself into a presentation session that may discovered by others.
See initial email on Second Screen Presentation WG mailing-list:
http://lists.w3.org/Archives/Public/public-webscreens/2014Nov/0011.html
Some user agents may wish to allow the user to initiate presentation from the browser instead of by triggering it via an action on the page. This is analogous to choosing "Print" from the browser menu instead of calling window.print().
In this scenario, the page should be able to designate a default presentation URL that will be shown when the user initiates presentation via the browser. This issue tracks the work to define the specification and the user-agent behavior around this URL.
The latest Editor's Draft needs to define the algorithms for the following:
7.1 The Screen Availability algorithm
7.2 The Start Session algorithm
7.3 The Join Session algorithm
7.4 The Close Session algorithm
7.5 The Presentation Initialization algorithm
We refer to the variable D in the "Starting a presentation session" algorithm [1] without first declaring and initializing it:
Add (S.url, S.id, S) to D.
Since we refer to D in many places and it holds global state, we should define D as a global variable, and refer to the global from within related algorithms. Something like:
Each XXXX has a <dfn>set of presentations<dfn>.
And then link to the global definition from within the algorithms, e.g.:
Add (S.url, S.id, S) to <a>set of presentations</a>.
What would be XXXX above i.e. what do we mean by "known by the user agent" specifically? Is the set of presentations associated with the document's origin similarly to e.g. Web Storage [2]? If so, we could reuse some of the prose from that spec and adapt.
[1] http://w3c.github.io/presentation-api/#starting-a-presentation-session
[2] http://www.w3.org/TR/webstorage/#the-sessionstorage-attribute
http://w3c.github.io/presentation-api/#algorithm-post-message
Consider additional binary datatypes? https://bugzilla.mozilla.org/show_bug.cgi?id=1080474#c22
Media flinging use case requires Presentation API to support multiple presentation devices at the same time [1].
Specification has to be updated to reflect that in different sections:
Currently we mix the API for controlling page and presenting page in NavigatorPresentation and developer will use navigator.presentation as the entry point.
Since we are providing more and more advance feature in this API (see #19), it's cumbersome to provide statement on the usage of each attribute/function.
Therefore I propose to move all presenting page APIs into a different interface, called PresentingContext. The example definition will looks like:
interface PresentingContext : EventTarget {
Promise<PresentationSession> getSession();
Sequence<PresentationSession> getSessions();
attribute EventHandler onsessionavailable;
};
partial interface Navigator {
readonly attibute PresentingContext presentingContext; // null if not presenting page
};
Currently we only provide the session initial/resumption/teardown algorithm for controlling page. Since Mozilla is the first implementation that use HTML5 in presenting side, we'd like to contribute the session management algorithm to spec.
Via http://lists.w3.org/Archives/Public/public-webscreens/2014Aug/0003.html
The specification does not define when the presenting user agent will be able to access the presentation session across page navigations.
One proposal is to have the PresentationSession implement Transferable so it can be passed to and from a SharedWorker.
Another option would be for the page to use session reconnection in a manner similar to the presenting page (see https://github.com/webscreens/presentation-api/issues/15).
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.