diff --git a/index.html b/index.html index db57754..3b6227a 100644 --- a/index.html +++ b/index.html @@ -65,22 +65,22 @@

.then(console.log('Share successful')); }); -

- 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. +

+ 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. + 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.

API definition

-
+

Navigator interface

@@ -95,48 +95,41 @@

The data argument is marked as "optional", but it is - effectively required; share will - throw a TypeError if called - with no arguments. WebIDL share() will throw 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. + 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. + 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.

- share method + share() method

- When the share method is called with argument + 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, reject p with - TypeError, and - abort these steps. +
    3. If none of data's members title, text, + or url are present, reject p with + TypeError, and abort these steps.
      4. -
    4. If data's url member is - present: +
    5. If data's url member is present:
      1. Let base be the this value's relevant @@ -145,38 +138,34 @@

      2. Let url be the result of running the URL parser on - data's url, with - base, and no encoding override. + data's url, with base, and no + encoding override.
      3. If url is failure, reject p with - TypeError, - and abort these steps. + TypeError, and abort these steps.
      4. Set data to a copy of data, with its - url field set to the result of running - the URL - serializer on url. + url field set to the result of running the + URL serializer + on url.
    6. If the method call was not triggered by user activation, reject p with - NotAllowedError, and - abort these steps. + "!promises-guide#reject-promise">reject p with a + "NotAllowedError" DOMException, and abort these + steps.
    7. In parallel:
      1. If there are no share targets available, reject - p with AbortError, and abort - these steps. + p with an "AbortError" DOMException, and + abort these steps.
      2. Present the user with a choice of one or more share targets, selected at the user agent's discretion. The user @@ -185,18 +174,16 @@

      3. If the user chose to cancel the share operation, reject - p with AbortError, and abort - these steps. + p with an "AbortError" DOMException, and + abort these steps.
      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 AbortError, and abort - these steps. + p with an "AbortError" DOMException, and + abort these steps.
      5. Once the data has been successfully transmitted to the target, 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. + 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.

-
+

ShareData dictionary

@@ -236,22 +222,30 @@

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

-
    -
  • - title: The title of the document being shared. May be - ignored by the target. -
    • -
  • - text: Arbitrary text that forms the body of the message - being shared. -
    • -
  • - url: A valid URL - string referring to a resource being shared. -
    • -
+
+
+ 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 valid URL string + referring to a resource being shared. +
+
These fields are USVString (as opposed to @@ -262,7 +256,7 @@

UTF-8).

- The url field can contain a url field can contain a relative URL. In this case, it will be automatically resolved relative to the current page location, just like a

-
+

Share targets

@@ -294,16 +288,15 @@

Each share target MAY be made conditionally available depending on the - ShareData payload delivered to the share - method. + 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. + words, the share() method is "fire and forget"; it does not wait + for the target to approve or reject the payload.

@@ -337,17 +330,42 @@

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 fields. For example, if the target has a "text" field but not a "URL" field, one solution is to concatenate both the - text and url fields of - ShareData and pass the result in the "text" field of the - target. + text and url fields of ShareData and pass the + result in the "text" field of the target.

+
+

+ Dependencies +

+

+ The following are defined in [[!WEBIDL]]: +

+
    +
  • + DOMException +
    • +
  • + AbortError +
    • +
  • + NotAllowedError +
    • +
+

+ TypeError + is defined by [[!ECMASCRIPT]]. +

+

Security and privacy considerations @@ -360,29 +378,28 @@

  • There is a requirement to not allow the website to learn which apps - are installed, or which app was chosen from - navigator.share, because this information could be - used for fingerprinting, as well as leaking details about the user's - device. + are installed, or which app was chosen from navigator.share(), + because this information could be used for fingerprinting, as well as + leaking details about the user's device.
  • Implementors will want to carefully consider what information is - revealed in the error message when navigator.share - is rejected. Even distinguishing between the case where no targets are + revealed in the error message when navigator.share() is + rejected. Even distinguishing between the case where no targets are available and user cancellation could reveal information about which apps are installed on the user's device.
    • -
  • There is a requirement that navigator.share - presents the user with a dialog asking them to select a target - application (even if there is only one possible target). This surface - serves as a security confirmation, ensuring that websites cannot - silently send data to native applications. +
  • There is a requirement that navigator.share() presents the + user with a dialog asking them to select a target application (even if + there is only one possible target). This surface serves as a security + confirmation, ensuring that websites cannot silently send data to + native applications.
  • Due to the capabilities of the API surface, - navigator.share is navigator.share() is available only in secure contexts (such as https:// schemes).
    • -
  • Use of navigator.share from a Use of navigator.share() from a private browsing mode might leak private data to a third-party application that does not respect the user's privacy setting. User agents could present @@ -390,11 +407,11 @@

    browsing mode, but this is not mandated as the chooser UI could be considered sufficient warning.

    • -
  • The data passed to navigator.share might be - used to exploit buffer overflow or other remote code execution - vulnerabilities in native applications that receive shares. There is no - general way to guard against this, but implementors will want to be - aware that it is a possibility. +
  • The data passed to navigator.share() might be used to + exploit buffer overflow or other remote code execution vulnerabilities + in native applications that receive shares. There is no general way to + guard against this, but implementors will want to be aware that it is a + possibility.

@@ -413,14 +430,13 @@

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 +

+ 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 recognise those members. These new + older implementations that don't recognize those members. These new members might also be added as optional "MAY" requirements.

@@ -428,21 +444,17 @@

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

-

- The share method throws 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 recognised - members (so as to not throw an error). 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 fields they rely on, to avoid having - errors surface in their program. +

+ The share() method throws 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 (so + as to not throw an error). 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 fields they + rely on, to avoid having errors surface in their program.

Editors of this spec will want to carefully consider the genericity of