diff --git a/level-2/index.html b/level-2/index.html index 7e867a5..2cfc5ac 100644 --- a/level-2/index.html +++ b/level-2/index.html @@ -2,536 +2,27 @@ + + - Web Share API - Level 2 + This specification has moved - - + - -
-

- This specification defines an API for sharing text, links and other - content to an arbitrary destination of the user's choice. -

-

- The available share targets are not specified here; they are provided - by the user agent. They could, for example, be apps, websites or - contacts. -

-
-
-
-
-

- Usage Examples -

-

- This example shows a basic share operation. In response to a button - click, this JavaScript code shares the current page's URL. -

- 
-        shareButton.addEventListener("click", async () => {
-          try {
-            await navigator.share({ title: "Example Page", url: "" });
-            console.log("Data was shared successfully");
-          } catch (err) {
-            console.error("Share failed:", err.message);
-          }
-        });
-
-

- Note that a url of '' refers to the current page - URL, just as it would in a link. Any other absolute or relative URL can - also be used. -

-

- In response to this call to navigator.share(), the user agent - would display a picker or chooser dialog, allowing the user to select a - target to share this title and the page URL to. + +

+

+ This specification has moved +

+
+
+

+ This incubated "Web Share - Level 2" document has been folded into the + official specification for the Web Share API.

-
-

- API definition -

-
-

- Navigator interface -

-

- The Navigator - interface is defined in [[HTML]]. -

- 
-          partial interface Navigator {
-            [SecureContext] boolean canShare(optional ShareData data = {});
-            [SecureContext] Promise<void> share(optional ShareData data = {});
-          };
-
-
- The data argument is marked as "optional", but it is - effectively required; share() will return a rejected promise - with a TypeError if called with no arguments. WebIDL - mandates that it be - optional because the dictionary members are all optional. See - WebIDL Issue - #130. -
-

- User agents that do not support sharing SHOULD NOT expose - share() on the Navigator interface. -

-
- The above statement is designed to permit feature detection. If - share() is present, there is a reasonable expectation that it - will work and present the user with at least one share target. - Clients can use the presence or absence of this method to determine - whether to show UI that triggers its use. -
-
-

- canShare() method -

-

- canShare(data) MUST return - true unless - share(data) would reject with - TypeError, in which case it MUST return false. -

-
-
-

- share() method -

-

- When the share() method is called with argument - data, run the following steps: -

-
    -
  1. Let p be a new promise. -
    2. -
  2. If none of data's members title, text - or url are present: -
      -
    1. If data's member files is not present or - is empty, or if the implementation does not support file - sharing, reject p with TypeError, and abort - these steps. -
      2. -
    -
    3. -
  3. If data's url member is present: -
      -
    1. Let base be the this value's - relevant - settings object's API - base URL. -
      2. -
    2. Let url be the result of running the - URL parser on - data's url, with base, and no - encoding override. -
      3. -
    3. If url is failure, reject p with - TypeError, and abort these steps. -
      4. -
    4. Set data to a copy of data, with its - url member set to the result of running the - URL serializer - on url. -
      5. -
    -
    4. -
  4. If the method call was not triggered by user - activation, or a file type is being blocked due to security - considerations, reject p with a - "NotAllowedError" DOMException, and abort these - steps. -
    5. -
  5. - In parallel: -
      -
    1. If there are no share targets available, - reject - p with an "AbortError" DOMException, and - abort these steps. -
      2. -
    2. Present the user with a choice of one or more share - targets, selected at the user agent's discretion. The user - MUST be given the option to cancel rather than choosing any of - the share targets. Wait for the user's choice. -
      3. -
    3. If the user chose to cancel the share operation, - reject - p with an "AbortError" DOMException, and - abort these steps. -
      4. -
    4. Activate the chosen share target, convert - data to a format suitable for ingestion into the - target, and transmit the converted data to the target. If - an error occurs starting the target or transmitting the data, - reject - p with an "AbortError" DOMException, and - abort these steps. -
      5. -
    5. Once the data has been successfully transmitted to the - target, resolve p with - undefined. -
      6. -
    -
    6. -
  6. Return p. -
    7. -
-

- The user agent MUST NOT allow the website to learn which share - targets are available, or the identity of the chosen target. -

-
- share() always shows some form of UI, to give the user a - choice of application and get their approval to invoke and send - data to a potentially native application (which carries a security - risk). For this reason, user agents are prohibited from showing any - kind of "always use this target in the future" option, or bypassing - the UI if there is only a single share target. -
-
- To determine if file sharing is supported by an implementation, - canShare() can be called with a dictionary containing only - files. -
-
-
-
-

- ShareData dictionary -

- 
-          dictionary ShareData {
-            USVString title;
-            USVString text;
-            USVString url;
-            FrozenArray<File> files;
-          };
-
-

- The ShareData dictionary consists of several optional - members: -

-
-
- title member -
-
- The title of the document being shared. May be ignored by the - target. -
-
- text member -
-
- Arbitrary text that forms the body of the message being shared. -
-
- url member -
-
- A URL string referring to a resource being shared. -
-
- files member -
-
- A File - array referring to files being shared. -
-
-
- The string members are USVString (as opposed to - DOMString) - because they are not allowed to contain invalid UTF-16 surrogates. This means the user agent - is free to re-encode them in any Unicode encoding (e.g., - UTF-8). -
-
- The url member can contain a relative URL. In this - case, it will be automatically resolved relative to the current page - location, just like a href on an a element, before being given - to the share target. -
-
-
-
-

- Share targets -

-

- A share target is the - abstract concept of a destination that the user agent will transmit the - share data to. What constitutes a share target is at the discretion of - the user agent. -

-

- A share target might not be directly able to accept a ShareData - (due to not having been written with this API in mind). However, it - MUST have the ability to receive data that matches some or all of the - concepts exposed in ShareData. To convert data to a format - suitable for ingestion into the target, the user agent SHOULD map - the members of ShareData onto equivalent concepts in the target. - It MAY discard members if necessary. The meaning of each member of the - payload is at the discretion of the share target. -

-

- Each share target MAY be made conditionally available depending on the - ShareData payload delivered to the share() method. -

-
- Once a share target has been given the payload, the share is considered - successful. If the target considers the data unacceptable or an error - occurs, it can either recover gracefully, or show an error message to - the end-user; it cannot rely on the sender to handle errors. In other - words, the share() method is "fire and forget"; it does not wait - for the target to approve or reject the payload. -
-
-

- Examples of share targets -

-

- The list of share targets can be populated from a variety of sources, - depending on the user agent and host operating system. For example: -

-
    -
  • Built-in service (e.g., "copy to clipboard"). -
    • -
  • Native applications written for the host operating system. -
    • -
  • Contacts (e.g., the user agent directly shares to a person from - the user's address book, using a specific app). -
    • -
  • Websites (e.g., the user agent fills in a template URL with the - members of the ShareData, then navigates to that URL in a new - browsing context). -
    • -
-
- There is an attempt to standardize the registration of websites to - receive share data for that final use case; see Web Share Target. -
-

- In some cases, the host operating system will provide a sharing or - intent system similar to Web Share. In these cases, the user agent - can simply forward the share data to the operating system and not - talk directly to native applications. -

-

- Mapping the ShareData to the share target (or operating - system)'s native format can be tricky as some platforms will not have - an equivalent set of members. For example, if the target has a "text" - member but not a "URL" member, one solution is to concatenate both - the text and url members of ShareData and pass - the result in the "text" member of the target. -

-
-
-
-

- Dependencies -

-

- The following are defined in [[WEBIDL]]: -

- -

- TypeError - is defined by [[ECMASCRIPT]]. -

-
-
-

- Security and privacy considerations -

-

- Web Share enables data to be sent from websites to native applications. - While this ability is not unique to Web Share, it does come with a - number of potential security issues that can vary in severity - (depending on the underlying platform). -

- -
-
-

- Extensibility of this API -

-

- The Web Share API is designed to be extended in the future by way of - new members added to the ShareData dictionary, to allow both - sharing of new types of data (e.g., images) and strings - with new semantics (e.g. author). -

-
- This doesn't mean user agents can add whatever members they like. It - means that new members can be added to the standard in the future. -
-

- The three members title, text, and url, are part - of the base feature set, and implementations that provide - navigator.share() need to accept all three. Any new members that - are added in the future will be individually - feature-detectable, to allow for backwards-compatibility with - older implementations that don't recognize those members. These new - members might also be added as optional "MAY" requirements. -

-
- There is an open - discussion about how to provide feature-detection for dictionary - members. Web Share will use the mechanism produced by that discussion. -
-

- The share() method returns a rejected promise with a - TypeError if none of the specified members are present. The - intention is that when a new member is added, it will also be added to - this list of recognized members. This is for future-proofing - implementations: if a web site written against a future version of this - spec uses only new members (e.g., - navigator.share({image: x})), it will be valid in future - user agents, but a TypeError on user agents implementing an - older version of the spec. Developers will be asked to feature-detect - any new members they rely on, to avoid having errors surface in their - program. -

-

- Editors of this spec will want to carefully consider the genericity of - any new members being added, avoiding members that are closely - associated with a particular service, user agent or operating system, - in favour of members that can potentially be applied to a wide range of - platforms and targets. -

-
-
-
-

- Acknowledgments -

-

- Thanks to the Web - Intents team, who laid the groundwork for the web app - interoperability use cases. In particular, Paul Kinlan, who did a lot of early - advocacy for Web Share. -

-
-
-

- Changes since Level 1 -

- -