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 o mesmo compartilhamento fornecido pelo sistema recursos como apps específicos da plataforma. A API Web Share possibilita que apps da Web compartilhem links, textos e arquivos com outros aplicativos instalados no dispositivo da mesma como apps específicos da plataforma.

.
Seletor de destino de compartilhamento no nível do sistema com um PWA instalado como opção.
Seletor de destino 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:

  • Ela só pode ser usada em um site acessado via 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. Como invocá-lo pelo gerenciador onload é impossível.
  • Ele pode compartilhar URLs, textos ou arquivos.

Compatibilidade com navegadores

  • Chrome: 89.
  • Borda: 93.
  • Firefox: atrás de uma sinalização.
  • Safari: 12.1.

Origem

Como compartilhar links e texto

Para compartilhar links e textos, use o método share(), que é um protocolo baseado em promessas com um objeto de propriedades obrigatório. Para evitar que o navegador gere uma TypeError, o objeto deve conter pelo menos um das seguintes propriedades: title, text, url ou files. Você podem, por exemplo, compartilhar texto sem um URL ou vice-versa. Permitindo os três os membros expandem 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 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 seu site tenha vários URLs para o mesmo conteúdo, compartilhe o URL canônico em vez do atual. Em vez de compartilhar document.location.href, verifique se há uma tag <meta> do URL canônico em o <head> da página e compartilhar isso. Isso proporcionará uma experiência melhor usuário. Ela não apenas evita redirecionamentos, como também garante que um URL compartilhado seja veiculado. a experiência do usuário correta para determinado cliente. Por exemplo, se um amigo compartilha um URL para dispositivos móveis e o analisa em um computador desktop, você 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});

Compartilhamento de arquivos

Para compartilhar arquivos, primeiro teste e chame navigator.canShare(). Em seguida, inclua um 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 lida com detecção de recursos testando 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 conferir 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>

Saiba como isso funciona em uma demonstração do Glitch. e consultar o código-fonte. A falha em fornecer o atributo vai 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 fim de ano no Google. Todo dezembro, comemore a época 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 perfeita para dispositivos móveis. Nos anos anteriores, a equipe removeu os botões de compartilhamento dos dispositivos móveis porque o espaço era e não podiam justificar ter várias metas de compartilhamento.

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

Suporte ao navegador

O suporte do navegador para a API Web Share é diferenciado, e é recomendável usar o recurso (conforme descrito nos exemplos de código anteriores) em vez de presumir que um determinado método é suporte.

Veja uma breve descrição do suporte a esse recurso. Para informações detalhadas, acesse um dos links de suporte.

navigator.canShare()

Compatibilidade com navegadores

  • Chrome: 89.
  • Borda: 93.
  • Firefox: atrás de uma sinalização.
  • Safari: 14

Origem

navigator.share()

Compatibilidade com navegadores

  • Chrome: 89.
  • Borda: 93.
  • Firefox: atrás de uma sinalização.
  • Safari: 12.1.

Origem

Mostrar suporte à API

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

Envie um tweet para @ChromiumDev usando a hashtag #WebShare e informe onde e como você o utiliza.