Recebendo dados compartilhados com a API Web Share Target

Em um dispositivo móvel ou desktop, o compartilhamento deve ser tão simples quanto clicar no botão Compartilhar, escolher um aplicativo e escolher com quem compartilhar. Por exemplo, você pode querer compartilhar um artigo interessante, enviando-o por e-mail para amigos ou tweetando para o mundo.

No passado, apenas aplicativos específicos da plataforma podiam se registrar no sistema operacional para receber compartilhamentos de outros aplicativos instalados. Mas com a API Web Share Target, os aplicativos da web instalados podem se registrar no sistema operacional subjacente como um destino de compartilhamento para receber conteúdo compartilhado.

# Veja o Web Share Target em ação

1. Usando o Chrome 76 ou posterior para Android, ou Chrome 89 ou posterior no desktop, abra a demonstração Web Share Target .
2. Quando solicitado, clique em Instalar para adicionar o aplicativo à tela inicial ou use o menu do Chrome para adicioná-lo à tela inicial.
3. Abra qualquer aplicativo que suporte compartilhamento ou use o botão Compartilhar no aplicativo de demonstração.
4. No seletor de destino, escolha Web Share Test .

Após o compartilhamento, você deve ver todas as informações compartilhadas no aplicativo da web de destino para compartilhamento web.

# Registre seu aplicativo como um alvo de compartilhamento

Para registrar seu aplicativo como um alvo de compartilhamento, ele precisa atender aos critérios de instalabilidade do Chrome. Além disso, para que um usuário possa compartilhar com seu aplicativo, ele deve adicioná-lo à tela inicial. Isso evita que os sites se adicionem aleatoriamente ao seletor de intent de compartilhamento do usuário e garante que o compartilhamento seja algo que os usuários desejam fazer com seu aplicativo.

# Atualize o manifesto do seu aplicativo da web

Para registrar seu aplicativo como um alvo de compartilhamento, adicione uma entrada share_target ao manifesto do aplicativo da web. Isso informa ao sistema operacional para incluir seu aplicativo como uma opção no seletor de intent. O que você adicionar ao manifesto irá controlar os dados que seu aplicativo irá aceitar. Existem três cenários comuns para a entrada share_target

• Aceitando informações básicas
• Aceitando alterações de aplicativo
• Aceitando arquivos

# Aceitando informações básicas

Se seu aplicativo de destino aceita apenas 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 seu aplicativo já tem um esquema de URL de compartilhamento, você pode substituir os valores de param com os seus parâmetros de consulta existentes. Por exemplo, se o seu esquema de URL de compartilhamento usa body vez de text, você pode substituir "text": "text" por "text": "body" .

O valor padrão do method "GET" se não for fornecido. O enctype, não mostrado neste exemplo, indica otipo de codificação dos dados. Para o método "GET", enctype tem como padrão "application/x-www-form-urlencoded" e é ignorado se for configurado como qualquer outra coisa.

# Aceitando alterações do aplicativo

Se os dados compartilhados alterarem o aplicativo de destino de alguma forma - por exemplo, salvando um marcador no aplicativo de destino - defina o valor method "POST" e inclua o campo enctype. O exemplo abaixo cria um favorito no aplicativo de destino, portanto, usa "POST" para method e "multipart/form-data" para enctype :

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

# Aceitando arquivos

Tal como acontece com as alterações do aplicativo, aceitar arquivos requer que o method seja "POST" e que enctype esteja presente. Além disso, enctype deve ser "multipart/form-data" e deve-se adicionar entrada files.

Você também deve adicionar uma matriz files definindo os tipos de arquivos que seu aplicativo aceita. Os elementos da matriz são entradas com dois membros: um campo name e um campo de accept. O campo accept leva um tipo MIME, uma extensão de arquivo ou uma matriz contendo ambos. É melhor fornecer uma matriz que inclua um tipo MIME e uma extensão de arquivo, pois os sistemas operacionais têm diferentes preferências.

{
  "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"
        }
      ]
    }
  }
}

# Manipulando o conteúdo de entrada

A forma como você lida com os dados compartilhados de entrada deve ser feita de acordo com suas preferências e depende do seu aplicativo. Por exemplo:

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

# Processando 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 de action. O navegador então gera uma string de consulta usando os valores codificados por URL fornecidos no manifesto. Por exemplo, se o aplicativo de compartilhamento fornecer title e text, a string de consulta será ?title=hello&text=world. Para processar isso, use um DOMContentLoaded em sua página de primeiro plano e analise a string de consulta:

window.addEventListener('DOMContentLoaded', () => {
  const parsedUrl = new URL(window.location);
  // searchParams.get() irá lidar apropriadamente com a decodificação dos valores.
  console.log('Title shared: ' + parsedUrl.searchParams.get('title'));
  console.log('Text shared: ' + parsedUrl.searchParams.get('text'));
  console.log('URL shared: ' + parsedUrl.searchParams.get('url'));
});

Certifique-se de usar um service worker para pré-armazenar em cache a página action para que ela carregue rapidamente e funcione de forma confiável, mesmo se o usuário estiver offline. Workbox é uma ferramenta que pode ajudá-lo a implementar o pré-cache em seu service worker.

# Processando compartilhamentos POST

Se seu method for "POST" , como seria se seu aplicativo de destino aceitasse um favorito salvo ou arquivos compartilhados, o corpo da solicitação POST contém os dados passados pelo aplicativo de compartilhamento, codificados usando o enctype informado no manifesto .

A página de primeiro plano não pode processar esses dados diretamente. Como a página vê os dados como uma solicitação, ela os repassa para o service worker, onde você pode interceptá-los com um listener de evento de fetch. A partir daqui, você pode passar os dados de volta para a página de primeiro plano usando postMessage() ou passá-los para o servidor:

self.addEventListener('fetch', event => {
  const url = new URL(event.request.url);
  // Se esta for uma solicitação POST de entrada para a
  // URL de "ação" registrada, responda a ela.
  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);
    })());
  }
});

# Verificando o conteúdo compartilhado

Certifique-se de verificar os dados de entrada. Infelizmente, não há garantia de que outros aplicativos compartilharão o conteúdo apropriado no parâmetro certo.

Por exemplo, no Android, o campo url ficará vazio porque não é compatível com o sistema de compartilhamento do Android. Em vez disso, os URLs geralmente aparecem no campo text ou, ocasionalmente, no campo title.

# Suporte de navegadores

Desde o início de 2021, a API Web Share Target é compatível com:

• Chrome e Edge 76 ou posterior no Android.
• Chrome 89 ou posterior no ChromeOS.

Em todas as plataformas, seu aplicativo da web deve ser instalado antes de aparecer como um alvo potencial para receber dados compartilhados.

# Aplicativos de amostra

• Squoosh
• Scrapbook PWA

# Mostrar suporte para a API

Pretende usar a API Web Share Target? Seu apoio público ajuda a equipe do Chromium a priorizar os recursos e mostra a outros fornecedores de navegadores como é fundamental apoiá-los.

Envie um tweet para @ChromiumDev usando a hashtag #WebShareTarget e diga-nos onde e como você está usando a API.