Integrar a IU de compartilhamento do SO usando a API Web Share

Os apps da Web podem usar os mesmos recursos de compartilhamento fornecidos pelo sistema que os apps específicos da plataforma.

Joe medley
Joe Medley

Com a API Web Share, os apps da Web podem usar os mesmos recursos de compartilhamento fornecidos pelo sistema que os apps específicos da plataforma. A API Web Share permite que apps da Web compartilhem links, textos e arquivos com outros apps instalados no dispositivo da mesma maneira que apps específicos da plataforma.

Seletor de segmentação de compartilhamento no nível do sistema com um PWA instalado como opção.
Seletor de segmentação de compartilhamento no nível do sistema com um PWA instalado como opção.

Recursos e limitações

O compartilhamento na Web tem os seguintes recursos e limitações:

  • Só pode ser usado em um site acessado via HTTPS.
  • Se o compartilhamento acontecer em um iframe de terceiros, o atributo allow vai precisar ser usado.
  • Ele precisa ser invocado em resposta a uma ação do usuário, como um clique. Não é possível invocá-lo usando o gerenciador onload.
  • Ela pode compartilhar URLs, textos ou arquivos.

Compatibilidade com navegadores

  • 89
  • 93
  • 12.1

Origem

Para compartilhar links e texto, use o método share(), que é um método baseado em promessa com um objeto de propriedades obrigatório. Para evitar que o navegador gere uma TypeError, o objeto precisa conter pelo menos uma destas propriedades: title, text, url ou files. É possível, por exemplo, compartilhar texto sem um URL ou vice-versa. Permitir os três membros aumenta a flexibilidade dos casos de uso. Imagine se, depois de executar o código abaixo, o usuário escolhesse um aplicativo de e-mail como destino. O parâmetro title pode se tornar o assunto do e-mail, o text, o corpo da mensagem e os arquivos, os anexos.

if (navigator.share) {
  navigator.share({
    title: 'web.dev',
    text: 'Check out web.dev.',
    url: 'https://web.dev/',
  })
    .then(() => console.log('Successful share'))
    .catch((error) => console.log('Error sharing', error));
}

Caso o site tenha vários URLs para o mesmo conteúdo, compartilhe o URL canônico da página em vez do atual. Em vez de compartilhar document.location.href, verifique se há uma tag <meta> de URL canônico no <head> da página e compartilhe essa informação. Isso proporcionará uma experiência melhor ao usuário. Isso não apenas evita redirecionamentos, mas também garante que um URL compartilhado ofereça a experiência do usuário correta para um determinado cliente. Por exemplo, se um amigo compartilhar um URL para dispositivos móveis e você abrir o URL em um computador desktop, verá uma versão para computador:

let url = document.location.href;
const canonicalElement = document.querySelector('link[rel=canonical]');
if (canonicalElement !== null) {
    url = canonicalElement.href;
}
navigator.share({url});

Como compartilhar arquivos

Para compartilhar arquivos, primeiro teste e chame navigator.canShare(). Em seguida, inclua uma matriz de arquivos na chamada para navigator.share():

if (navigator.canShare && navigator.canShare({ files: filesArray })) {
  navigator.share({
    files: filesArray,
    title: 'Vacation Pictures',
    text: 'Photos from September 27 to October 14.',
  })
  .then(() => console.log('Share was successful.'))
  .catch((error) => console.log('Sharing failed', error));
} else {
  console.log(`Your system doesn't support sharing files.`);
}

Observe que o exemplo processa a detecção de recursos testando para navigator.canShare() em vez de navigator.share(). O objeto de dados transmitido para canShare() oferece suporte apenas à propriedade files. Certos tipos de arquivos de áudio, imagem, PDF, vídeo e texto podem ser compartilhados. Consulte Extensões de arquivo permitidas no Chromium para ver uma lista completa. Outros tipos de arquivo podem ser adicionados no futuro.

Compartilhamento em iframes de terceiros

Para acionar a ação de compartilhamento em um iframe de terceiros, incorpore o iframe com o atributo allow com um valor de web-share:

<!-- On https://example.com/index.html -->
<iframe allow="web-share" src="https://third-party.example.com/iframe.html"></iframe>

Confira como isso funciona em uma demonstração do Glitch e confira o código-fonte. Deixar de fornecer o atributo resultará em uma NotAllowedError com a mensagem Failed to execute 'share' on 'Navigator': Permission denied.

Estudo de caso do Siga o Papai Noel

O app Siga o Papai Noel mostrando um botão de compartilhamento.
Botão de compartilhamento do Siga o Papai Noel.

O Siga o Papai Noel, um projeto de código aberto, é uma tradição de feriados no Google. Todo dezembro, você pode comemorar a temporada com jogos e experiências educativas.

Em 2016, a equipe do Siga o Papai Noel usou a API Web Share no Android. Essa API era ideal para dispositivos móveis. Nos anos anteriores, a equipe removeu botões de compartilhamento em dispositivos móveis porque o espaço é um valor extra, e eles não poderiam justificar ter vários alvos de compartilhamento.

No entanto, com a API Web Share, eles conseguiram apresentar um botão, que salva os pixels preciosos. Eles também descobriram que os usuários compartilharam com o Web Share cerca de 20% mais do que os usuários sem a API ativada. Acesse o Siga o Papai Noel para conferir o Web Share em ação.

Suporte ao navegador

A compatibilidade do navegador com a API Web Share é variada. Recomendamos que você use a detecção de recursos, conforme descrito nos exemplos de código anteriores, em vez de presumir que haja suporte para um método específico.

Veja um breve resumo do suporte para esse recurso. Para informações detalhadas, acesse um dos links de suporte.

navigator.canShare()

Compatibilidade com navegadores

  • 89
  • 93
  • 14

Origem

navigator.share()

Compatibilidade com navegadores

  • 89
  • 93
  • 12.1

Origem

Mostrar suporte à API

Você planeja usar a API Web Share? Seu suporte público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegador como é fundamental oferecer suporte a eles.

Envie um tweet para @ChromiumDev com a hashtag #WebShare e conte para a gente onde e como você está usando a hashtag.