Introducing the Web Share API

Good news, everybody! Matt Giuca on the Chrome team has been working on a simple API called Web Share that allows websites to invoke the native sharing capabilities of the host platform.

There have been a number of ways to invoke native sharing capabilities on the platform, but they all have significant drawbacks. There was Web Intents (dead), there is protocol handling via registerProtocolHandler but this has zero support on mobile, there is direct sharing to a well-known service URL such as Twitter's, and there is also the Android intent: URL syntax (which was, unfortunately, Android-only, and required apps to opt-in).

The Web Share API is important because it gives the user control of how and where the data is shared.

In Chrome 55 (Beta as of October 2016), we've enabled an Origin Trial that lets you integrate the Web Share API into your site. The origin trial means this API is not generally available to all sites; instead you need to register to get access during the trial phase. Over this time, the API will likely change and break in unexpected ways, which is why we are looking for as much feedback as possible.

The Web Share API is a promise -based, single method API that takes an object with properties named title, text and url.

navigator.share({
    title: document.title,
    text: "Hello World",
    url: window.location.href
}).then(() => console.log('Successful share'))
.catch(() => console.log('Error sharing:', error));

Once invoked it will bring up the native picker (see video) and allow you to share the data with the app chosen by the user.

This API has a few constraints:

• You need to host your site in a secure context (typically https).
• You only need to supply one of text or url, not both.
• You can only invoke the API as a result of a user gesture. (For example, you can't call navigator.share() in an onload handler.)
• The property values that you pass into the API must all be strings.

How to get this working

The process is pretty simple:

1. Get the Chrome Beta Channel on Android (as of October 2016).
2. Sign up for the Origin Trial.
3. Integrate the Origin Trial tokens into your site (as long as it is on https).
4. Call navigator.share() in response to a user gesture.
5. Share!

Be progressive

The API is not available on all platforms, so you will have to gracefully handle the scenarios where you don't have the ability to call. I try to progressively enhance as much as possible, and the process that I follow on my blog is to:

1. Use your preferred sharing service via a simple <a> (intent: URL with Twitter fallback is an example I use).
2. Check the availability of the API (navigator.share !== undefined).
3. Wait for the content to be available and then find the sharing element.
4. Intercept and prevent the default behavior of the click.
5. Call navigator.share().

Share the correct URL

You should also think about the URL that you want to share. In many cases the user will be on a mobile device and your site might have an "m." url, or a url that is custom to user's context. You can use the fact that there might be a canonical URL on your page to provide a better experience to the user. For example, you might do:

var url = document.location;
var canonicalElement = document.querySelector('link[rel=canonical]');
if(canonicalElement !== undefined) {
    url = canonicalElement.href;
}

Where can I get more information

You can get all the relevant information at ChromeStatus, but to save you a click, here are the important links:

• Launch tracking bug in Chrome
• Intent to implement
• Sample
• Share explainer
• Web Share in WICG
• Discussion on Discourse

Future work will also level the playing field for web apps, by allowing them to register to be a "share receiver", enabling web-to-app sharing, app-to-web sharing and web-to-web sharing. Personally, I am incredibly excited about this.