Web Share API

Abstract

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.

Status of This Document

This specification was published by the Web Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This is an early draft of the Web Share spec.

1. Usage Examples

This section is non-normative.

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

Example 1

: Basic usage

shareButton.addEventListener('click', () => {
  navigator.share({title: 'Example Page', url: ''})
      .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.

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.

2. API definition

2.1 `Navigator` interface

The Navigator interface is defined in [HTML].

partial interface Navigator {
    [SecureContext]
    Promise<void> share(ShareData data);
};

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

Note

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 should be able to use the presence or absence of this method to determine whether to show UI that triggers its use.

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

Let p be a newly created promise.
If data's url member is present:
1. Let url be the result of running the URL parser on data's url, with the document's base URL, and no encoding override.
2. If url is failure, reject p with TypeError, and abort these steps.
3. Set data to a copy of data, with its url field set to the result of running the URL serializer on url.
If the method call was not triggered by user activation, reject p with SecurityError, and abort these steps.
In parallel:
1. If there are no share targets available, reject p with AbortError, 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 MUST be given the option to cancel rather than choosing any of the share targets. Wait for the user's choice.
3. If the user chose to cancel the share operation, reject p with AbortError, 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.
5. Once the data has been successfully transmitted to the target, resolve p.
Return p.

Note

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 MUST still show UI even if there is only a single share target, and MUST NOT perform any kind of "always use this target" to bypass the UI in subsequent share operations.

2.2 `ShareData` dictionary

dictionary ShareData {
    USVString title;
    USVString text;
    USVString url;
};

The ShareData dictionary consists of several optional fields:

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.

Note

These fields are USVString (as opposed to DOMString) because they must not contain invalid UTF-16 surrogates. This means the user agent is free to re-encode them in any Unicode encoding (e.g., UTF-8).

Note

The url field may 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.

3. Share targets

A 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 may 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 fields of ShareData onto equivalent concepts in the target. It MAY discard fields if necessary. The meaning of each field 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.

Note

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, the target should either recover gracefully, or show an error message to the end-user, because the sender is not going to know that an error occurred. In other words, the share method is "fire and forget"; it does not wait for the target to approve or reject the payload.

4. Security and privacy considerations

This section is non-normative.

Implementations should observe the following security and privacy advice.

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 may vary in severity (depending on the underlying platform).

User agents MUST NOT allow the website to learn which apps are installed, or which app was chosen from navigator.share. This information could be used for fingerprinting, as well as leaking details about the user's device.
Implementors should carefully consider what information is revealed in the error message when navigator.share is rejected. Even distinguishing between the case where no targets are available and user cancellation may reveal information about which apps are installed on the user's device.
On every call to navigator.share, the user MUST be presented 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 available only in secure contexts (such as https:// schemes).
Use of navigator.share from a private browsing mode may leak private data to a third-party application that does not respect the user's privacy setting. User agents should consider presenting additional warnings or disabling the feature entirely when in a private browsing mode.
The data passed to navigator.share may 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 should be aware that it is a possibility.

B. References

B.1 Normative references

[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[URL]: URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/
[WEBIDL]: Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/

B.2 Informative references

[WEBIDL-LS]: Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[rfc2781]: UTF-16, an encoding of ISO 10646. P. Hoffman; F. Yergeau. IETF. February 2000. Informational. URL: https://tools.ietf.org/html/rfc2781
[rfc3629]: UTF-8, a transformation format of ISO 10646. F. Yergeau. IETF. November 2003. Internet Standard. URL: https://tools.ietf.org/html/rfc3629

Web Share API

Draft Community Group Report 20 June 2017

Abstract

Status of This Document

1. Usage Examples

2. API definition

2.1 `Navigator` interface

2.2 `ShareData` dictionary

4. Security and privacy considerations

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

Abstract

Status of This Document

1. Usage Examples

2. API definition

2.1 Navigator interface

2.1.1 share method

2.2 ShareData dictionary

3. Share targets

3.1 Examples of share targets

4. Security and privacy considerations

A. Acknowledgments

B. References

B.1 Normative references

B.2 Informative references

2.1 `Navigator` interface

2.1.1 `share` method

2.2 `ShareData` dictionary