Como receber dados compartilhados com a API Web Share Target

Compartilhamento em dispositivos móveis e computadores simplificado com a API Web Share Target

Pete LePage
Joe Medley
Joe Medley
GitHub

Em um dispositivo móvel ou computador, o compartilhamento é tão simples quanto clicar no botão Compartilhar. escolher um aplicativo e escolher com quem compartilhar. Por exemplo, talvez você queira compartilhar um artigo interessante por e-mail ou twittando para amigos o mundo.

Antes, apenas aplicativos específicos da plataforma podiam ser registrados no sistema operacional para receber compartilhamentos de outros apps instalados. Mas com a API Web Share Target, os aplicativos da web instalados podem ser registrados no sistema operacional subjacente como alvo de compartilhamento para receber conteúdo compartilhado.

Smartphone Android com a opção "Compartilhar por" gaveta aberta.
Seletor de destino de compartilhamento no nível do sistema com um PWA instalado como opção.

Veja o Destino de compartilhamento na Web em ação

  1. Chrome 76 ou mais recente para Android ou Chrome 89 ou mais recente computador, abra a demonstração do alvo de compartilhamento da Web.
  2. Quando solicitado, clique em Instalar para adicionar o app à tela inicial. use o menu do Google Chrome para adicioná-lo à sua tela inicial.
  3. Abra qualquer app compatível com compartilhamento ou use o botão "Compartilhar" no app de demonstração.
  4. No seletor de destino, escolha Teste de compartilhamento da Web.

Depois de compartilhar, você poderá ver todas as informações compartilhadas em o app da Web de destino de compartilhamento da Web.

Registrar o app como um alvo de compartilhamento

Para registrar seu app como um alvo de compartilhamento, é necessário atender aos requisitos e os critérios de instalação. Além disso, antes que um usuário possa compartilhar ao seu app, ele precisa adicioná-lo à tela inicial dele. Isso impede que os sites adicionando-se aleatoriamente ao seletor de intent de compartilhamento do usuário e garante que compartilhar é algo que os usuários querem fazer com seu app.

Atualizar o manifesto do app da Web

Para registrar seu app como um alvo de compartilhamento, adicione uma entrada share_target à Web manifesto do app. Isso instrui o sistema operacional a incluir seu app como uma opção no seletor de intents. O que você adiciona ao manifesto controla os dados que seu app aceitará. Há três cenários comuns para o share_target entrada:

  • Como aceitar informações básicas
  • Aceitando alterações no aplicativo
  • Aceitando arquivos
.

Como aceitar informações básicas

Se o aplicativo apenas aceita informações básicas, como dados, links, e texto, adicione o seguinte ao arquivo manifest.json:

"share_target": {
  "action": "/share-target/",
  "method": "GET",
  "params": {
    "title": "title",
    "text": "text",
    "url": "url"
  }
}

Se o aplicativo já tiver um esquema de URL de compartilhamento, substitua o params com seus parâmetros de consulta existentes. Por exemplo, se o URL de compartilhamento usa body em vez de text, substitua "text": "text" por "text": "body".

O valor padrão de method será "GET" se não for fornecido. O campo enctype, e não mostrado neste exemplo, indica o tipo de codificação dos dados. Para o método "GET", enctype é definido como "application/x-www-form-urlencoded" por padrão. será ignorado se estiver definido como qualquer outra coisa.

Aceitando alterações no aplicativo

Se os dados compartilhados mudarem o aplicativo de destino (por exemplo, salvar um favorito no aplicativo de destino. Defina o valor method como "POST" e inclua no campo enctype. O exemplo abaixo cria um favorito no app de destino, então ele usa "POST" para o method e "multipart/form-data" para o enctype:

{
  "name": "Bookmark",
  "share_target": {
    "action": "/bookmark",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "url": "link"
    }
  }
}

Aceitando arquivos

Como acontece com as mudanças no aplicativo, aceitar arquivos exige que method seja "POST" e que enctype esteja presente. Além disso, enctype precisa ser "multipart/form-data" e uma entrada files precisam ser adicionadas.

Também é necessário adicionar uma matriz files definindo os tipos de arquivos aceitos pelo app. A elementos de matriz são entradas com dois membros: um campo name e um accept . O campo accept usa um tipo MIME, uma extensão de arquivo ou uma matriz que contenham ambos. É melhor fornecer uma matriz que inclua um Tipo MIME e uma extensão de arquivo, já que os sistemas operacionais diferem em quais eles preferem.

{
  "name": "Aggregator",
  "share_target": {
    "action": "/cgi-bin/aggregate",
    "method": "POST",
    "enctype": "multipart/form-data",
    "params": {
      "title": "name",
      "text": "description",
      "url": "link",
      "files": [
        {
          "name": "records",
          "accept": ["text/csv", ".csv"]
        },
        {
          "name": "graphs",
          "accept": "image/svg+xml"
        }
      ]
    }
  }
}

Processar o conteúdo recebido

A forma como você lida com os dados compartilhados recebidos é você e depende do seu app. Por exemplo:

  • Um cliente de e-mail pode redigir um novo e-mail usando title como assunto de uma e-mail, com text e url concatenados como o corpo.
  • Um app de rede social poderia redigir uma nova postagem ignorando title, usando text como o corpo da mensagem e adição de url como um link. Se text for ausente, o app também poderá usar url no corpo. Se url estiver ausente, o app pode verificar text procurando um URL e adicioná-lo como um link.
  • Um app de compartilhamento de fotos pode criar uma nova apresentação de slides usando title como o título da apresentação de slides, text como descrição e files como imagens da apresentação de slides.
  • Um app de mensagens de texto pode criar o rascunho de uma nova mensagem usando text e url concatenados e descartando title.

Como processar compartilhamentos GET

Se o usuário selecionar seu aplicativo, e seu method for "GET" (o padrão), o navegador abre uma nova janela no URL action. Em seguida, o navegador gera uma string de consulta usando os valores codificados para URL fornecidos no manifesto. Por exemplo, se o app de compartilhamento fornecer title e text, a string de consulta será ?title=hello&text=world Para processar isso, use um DOMContentLoaded listener de eventos na página de primeiro plano e analise a string de consulta:

window.addEventListener('DOMContentLoaded', () => {
  const parsedUrl = new URL(window.location);
  // searchParams.get() will properly handle decoding the values.
  console.log('Title shared: ' + parsedUrl.searchParams.get('title'));
  console.log('Text shared: ' + parsedUrl.searchParams.get('text'));
  console.log('URL shared: ' + parsedUrl.searchParams.get('url'));
});

Use um service worker para pré-armazenar em cache o action para que ela seja carregada rapidamente e funcione de maneira confiável, mesmo que o usuário esteja off-line. O Workbox é uma ferramenta que pode ajudar você implementar o pré-armazenamento em cache no service worker.

Processando compartilhamentos POST

Se a method for "POST", como seria se o app de destino aceitasse uma favoritos ou arquivos compartilhados, o corpo da solicitação POST recebida conterá os dados transmitidos pelo aplicativo de compartilhamento, codificados usando o valor enctype fornecidos no manifesto.

A página em primeiro plano não pode processar esses dados diretamente. Como a página vê os dados como uma solicitação, a página a passa para o service worker, onde você pode interceptá-la com um fetch listener de eventos. Daqui, você pode transmitir os dados de volta para o primeiro plano usando postMessage() ou transmita-a ao servidor:

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  // If this is an incoming POST request for the
  // registered "action" URL, respond to it.
  if (event.request.method === 'POST' &&
      url.pathname === '/bookmark') {
    event.respondWith((async () => {
      const formData = await event.request.formData();
      const link = formData.get('link') || '';
      const responseUrl = await saveBookmark(link);
      return Response.redirect(responseUrl, 303);
    })());
  }
});

Como verificar conteúdo compartilhado

Um smartphone Android mostrando o app de demonstração com conteúdo compartilhado.
O app de destino de compartilhamento de exemplo.

Verifique os dados recebidos. Infelizmente, não há garantia de que outras os apps compartilharão o conteúdo adequado no parâmetro certo.

Por exemplo, no Android, o campo url estará vazio porque não há suporte para o sistema de compartilhamento do Android. Em vez disso, os URLs geralmente aparecem no campo text ou, ocasionalmente, no campo title.

Suporte ao navegador

A API Web Share Target é compatível, conforme descrito abaixo:

Em todas as plataformas, seu app da Web precisa ser instalado antes de aparecer como um público potencial para receber dados compartilhados.

Aplicativos de amostra

Mostrar suporte à API

Você planeja usar a API Web Share Target? 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 #WebShareTarget e informe onde e como você o utiliza.