Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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 is a work in progress. Wide review and feedback welcome.
This document was published by the Web Applications Working Group as a Working Draft using the Recommendation track.
Publication as a Working Draft does not imply endorsement by W3C and its Members.
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 2 November 2021 W3C Process Document.
This section is non-normative.
Because of how WebIDL dictionaries work, members passed to
share
(())
that are unknown to the user agent are ignored.
This can be a problem when sharing multiple members, but the user agent
doesn't support sharing one of those members. To be sure that every
member being passed is supported by the user agent, you can pass them
to canShare
()
individually to check if they are
supported.
Alternatively, you can adjust application's UI to not show UI components for unsupported members.
const data = {
title: "Example Page",
url: "https://example.com",
text: "This is a text to share",
someFutureThing: "some future thing",
};
// Things that are not supported...
const unsupported = Object.entries(data).filter(([key, value]) => {
return !navigator.canShare({ [key]: value });
});
This specification defines a policy-controlled permission identified by
the string "web-share"
. Its
default allowlist is 'self
'.
A document’s permission policy determines whether a
share
()
call immediately rejects with a
"NotAllowedError
" DOMException
.
This section is non-normative.
When this specification is used to present information in the user interface, implementors will want to follow the OS level accessibility guidelines for the platform.
This section is non-normative.
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).
share
()
,
because this information could be used for fingerprinting, as well as
leaking details about the user's device.
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.
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.
share
()
is only exposed in secure contexts (such as https://
schemes).
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
additional warnings or disable the feature entirely when in a private
browsing mode, but this is not mandated as the chooser UI could be
considered sufficient warning.
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.
Share targets that dereference a shared URL and forward that information on might inadvertently forward information that might be otherwise confidential. This can lead to unexpected information leakage if shares reference content that is only accessible by that application, the host on which it runs, or its network location.
Malicious sites might exploit share targets that leak information by providing URLs that ultimately resolve to local resources, including, but not limited to, "file:" URLs or local services that might otherwise be inaccessible. Even though this API limits shared URLS to "http:" and "https:", use of redirects to other URLs or tweaks to DNS records for hosts in those URLs might be used to cause applications to acquire content.
To avoid being used in these attacks, share targets can consume the URL, retrieve the content, and process that information without sharing it. For instance, a photo editing application might retrieve an image that is "shared" with it. A share target can also share the URL without fetching any of the referenced content.
Share targets that fetch content for the purposes of offering a
preview or for sharing content risk information leakage. Content
that is previewed and authorized by a user might be safe to
forward, however it is not always possible for a person to identify
when information should be confidential, so forwarding any content
presents a risk. In particular, the title
might be
used by an attacker to trick a user into misinterpreting the nature
of the content.
This section is non-normative.
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).
The three members title
, text
, and
url
, are part of the base feature set, and
implementations that provide 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.
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.
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, and SHOULD 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.
WebIDLpartial interface Navigator {
[SecureContext] Promise<undefined> share
(optional ShareData
data = {});
[SecureContext] boolean canShare
(optional ShareData
data = {});
};
dictionary ShareData
{
sequence<File> files
;
USVString title
;
USVString text
;
USVString url
;
};
This section is non-normative.
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.