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
GitHub

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 os apps da Web compartilhem links, textos e arquivos com outros apps instalados no dispositivo da mesma forma que os apps específicos da plataforma.

Seletor de destino de compartilhamento no nível do sistema com um PWA instalado como opção.
O seletor de destino de compartilhamento no nível do sistema com um PWA instalado como uma opção.

Recursos e limitações

A Compartilhamento na Web tem os seguintes recursos e limitações:

  • Ele só pode ser usado em um site acessado por HTTPS.
  • Se o compartilhamento acontecer em um iframe de terceiros, o atributo allow 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 pelo gerenciador onload.
  • Ele pode compartilhar URLs, textos ou arquivos.

Compatibilidade com navegadores

  • Chrome: 89.
  • Edge: 93.
  • Firefox: atrás de uma flag.
  • Safari: 12.1.

Origem

Compartilhamento de links e texto

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 das seguintes propriedades: title, text, url ou files. Por exemplo, é possível compartilhar texto sem um URL ou vice-versa. Permitir que todos os três membros expanda a flexibilidade dos casos de uso. Imagine que, depois de executar o código abaixo, o usuário escolheu um aplicativo de e-mail como alvo. 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));
}

Se o site tiver vários URLs para o mesmo conteúdo, compartilhe o URL canônico da página em vez do URL atual. Em vez de compartilhar document.location.href, você verificaria se há uma tag <meta> de URL canônico no <head> da página e a compartilharia. Isso vai 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 cliente específico. Por exemplo, se um amigo compartilhar um URL para dispositivos móveis e você acessar em um computador, uma versão para computador será exibida:

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

Compartilhamento de 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.`);
}

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

Compartilhamento em iframes de terceiros

Para acionar a ação de compartilhamento em um iframe de terceiros, insira 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 isso em ação em uma demonstração no Glitch e confira o código-fonte. Se o atributo não for fornecido, o resultado será 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 "Compartilhar" do Siga o Papai Noel.

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

Em 2016, a equipe do Siga o Papai Noel usou a API Web Share no Android. Essa API era perfeita para dispositivos móveis. Em anos anteriores, a equipe removeu os botões de compartilhamento em dispositivos móveis porque o espaço era limitado, e não era possível justificar a inclusão de vários alvos de compartilhamento.

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

Suporte ao navegador

O suporte do navegador à API Web Share é sutil, e é recomendável usar a detecção de recursos (conforme descrito nos exemplos de código anteriores) em vez de presumir que um método específico é compatível.

Confira um resumo do suporte a esse recurso. Para informações detalhadas, acesse um dos links de suporte.

navigator.canShare()

Compatibilidade com navegadores

  • Chrome: 89.
  • Edge: 93.
  • Firefox: atrás de uma flag.
  • Safari: 14.

Origem

navigator.share()

Compatibilidade com navegadores

  • Chrome: 89.
  • Edge: 93.
  • Firefox: atrás de uma flag.
  • Safari: 12.1.

Origem

Mostrar suporte para a API

Você planeja usar a API Web Share? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

Envie um tweet para @ChromiumDev usando a hashtag #WebShare e nos informe onde e como você está usando.