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 only available to sites in an opt-in basis; instead you need to register to get access during the trial phase. Over this time, the API may undergo breaking changes, 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(error => 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 need to supply at least one of text or url but may supply both if you like.
  • 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 (required as of October 2016, but won't be necessary once Chrome 55 reaches stable).
  2. Sign up for the Origin Trial.
  3. Insert the Origin Trial tokens into your site.
  4. Call navigator.share() in response to a user gesture.
  5. That's it, done. Share to your hearts content!

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 it. 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 element to be available intercept and prevent the default behavior of the click.
  4. 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.href;
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:

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.