Copyright © 2021 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. Other documents may supersede this document. 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 an Editor's Draft.
GitHub Issues are preferred for discussion of this specification.
Publication as an Editor's Draft does not imply endorsement by the W3C Membership.
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 15 September 2020 W3C Process Document .
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.
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
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
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 , SHOULD , and SHOULD NOT 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 = {});
};
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.