Escolha como os links no escopo abrem seu PWA com a captura declarativa de links

Thomas Steiner

O que é captura de link declarativa?

Clicar em links na web às vezes pode ser uma surpresa agradável. Por exemplo, clicar em um link de página da Web para o YouTube em um dispositivo móvel abre o app YouTube para iOS ou Android, caso esteja instalado. Porém, quando você instala o PWA do YouTube em um computador desktop e clica em um link, ele é aberto em uma guia do navegador.

Mas isso fica ainda mais complexo. E se o link não aparecer em um site, mas em uma mensagem de chat que você recebe em um dos apps de chat do Google? Em sistemas operacionais de computadores, que têm a noção de janelas de apps separadas, se o aplicativo já estiver aberto, uma nova janela ou guia deverá ser criada para cada clique no link? Quando você pensa sobre isso, há muitas maneiras de capturar links e navegações, incluindo, mas não se limitando a:

A captura declarativa de links é uma proposta para uma propriedade de manifesto de app da Web chamada "capture_links". Ela permite que os desenvolvedores determinem de forma declarativa o que vai acontecer quando o navegador for solicitado a navegar até um URL que está dentro do escopo de navegação do aplicativo, de um contexto fora desse escopo. Esta proposta não se aplica se o usuário já estiver no escopo de navegação (por exemplo, se o usuário abrir uma guia do navegador dentro do escopo e clicar em um link interno).

Algumas condições especiais, como clicar com o botão do meio em um link (ou clicar com o botão direito do mouse e, em seguida, "abrir em uma nova guia"), geralmente não acionam o comportamento de captura do link. Se um link é target=_self ou target=_blank não importa, para que os links clicados em uma janela do navegador (ou janela de um PWA diferente) sejam abertos no PWA, mesmo que normalmente causem uma navegação na mesma guia.

Casos de uso sugeridos

Exemplos de sites que podem usar essa API incluem:

  • PWAs que querem abrir uma janela, em vez de uma guia do navegador, quando o usuário clica em um link para eles. Em um ambiente de área de trabalho, muitas vezes faz sentido ter várias janelas de aplicativos abertas ao mesmo tempo.
  • PWAs de janela única, em que o desenvolvedor prefere ter apenas uma instância do app aberta a qualquer momento, com novas navegações concentrando a instância atual. Os subcasos de uso incluem:
    • Apps em que faz sentido ter apenas uma instância em execução (por exemplo, um player de música, um jogo).
    • Apps que incluem gerenciamento de vários documentos em uma única instância (por exemplo, uma barra de guias implementada em HTML).

Ativando via about://flags

Para testar a captura declarativa de links localmente, sem um token de teste de origem, ative a flag #enable-desktop-pwas-link-capturing em about://flags.

Como usar a captura de link declarativa?

Os desenvolvedores podem determinar de forma declarativa como os links precisam ser capturados usando o campo extra de manifesto do app da Web "capture_links". Ele usa uma string ou uma matriz de strings como valor. Se uma matriz de strings for fornecida, o user agent vai escolher o primeiro item compatível na lista, definindo "none" como padrão. Os valores a seguir são compatíveis:

  • "none" (padrão): nenhuma captura de link. Os links clicados que levam a esse escopo do PWA navegam normalmente sem abrir uma janela do PWA.
  • "new-client": cada link clicado abre uma nova janela do PWA no URL.
  • "existing-client-navigate": o link clicado será aberto em uma janela do PWA, se houver uma disponível, ou em uma nova janela se não estiver. Se houver mais de uma janela de PWA, o navegador poderá escolher uma arbitrariamente. Ele se comporta como "new-client" quando nenhuma janela está aberta. 📲 Cuidado! Essa opção pode levar à perda de dados, já que é possível sair arbitrariamente das páginas. Os sites devem estar cientes de que estão adotando esse comportamento ao escolher essa opção. Essa opção funciona melhor para sites "somente leitura" que não armazenam dados do usuário na memória, como players de música. Se a página que está sendo navegada tiver um evento beforeunload, o usuário verá a solicitação antes da conclusão da navegação.

Demonstração

A demonstração da captura declarativa de links consiste em duas demonstrações que interagem juntas:

  1. https://continuous-harvest-tomato.glitch.me/
  2. https://hill-glitter-tree.glitch.me/

O screencast abaixo mostra como os dois interagem. Elas mostram dois comportamentos diferentes, "new-client" e "existing-client-navigate". Teste os apps em estados diferentes, executados em uma guia ou como um PWA instalado, para ver a diferença no comportamento.

Segurança e permissões

A equipe do Chromium projetou e implementou a captura de link declarativa usando os princípios fundamentais definidos em Como controlar o acesso a recursos avançados da plataforma da Web, incluindo controle do usuário, transparência e ergonomia. Essa API permite que os sites tenham novas opções de controle adicionais. Primeiro, a possibilidade de abrir automaticamente os apps instalados em uma janela. Isso usa a interface já existente, mas possibilita que o site a acione automaticamente. Segundo, a capacidade de focar uma janela no próprio domínio e disparar um evento contendo o URL clicado. Isso permite que o site navegue de uma janela existente para uma nova página, substituindo o fluxo de navegação HTML padrão.

Migrar para a API Launch Handler

O teste de origem da API Declarative Link Capturing expirou em 30 de março de 2022 para o Chromium 97 e versões anteriores. Ela será substituída por um conjunto de novos recursos e APIs no Chromium 98 e versões mais recentes, que inclui a captura de links ativada pelo usuário e a API Launch Handler.

No Chromium 98, a captura automática de links agora é um comportamento de ativação do usuário, e não concedida no momento da instalação de um app da Web. Para ativar a captura de link, o usuário precisa iniciar um app instalado no navegador usando Abrir com e escolher Lembrar da minha escolha.

Exemplo da configuração "Abrir com" de um app instalado com a opção "Lembrar minha escolha" ativada.

Como alternativa, os usuários podem ativar ou desativar a captura de links em um app da Web específico na página de configurações do gerenciamento de apps.

Exemplo da página de configurações de um app instalado.

Por enquanto, a captura de links é um recurso exclusivo do ChromeOS. O suporte para Windows, macOS e Linux está em andamento.

Iniciar a API Handler

O controle de uma navegação de entrada é migrado para a API Launch Handler, que permite que os apps da Web decidam como um app da Web é iniciado em várias situações, como captura de links, compartilhamento de destino ou processamento de arquivos etc. Para migrar da API declarativa de captura de links para a API Launch Handler:

  1. Registre seu site no teste de origem do gerenciador de inicialização e coloque a chave de teste de origem no seu app da Web.

  2. Adicione uma entrada "launch_handler" ao manifesto do site.

    • Para usar "capture_links": "new-client", adicione:"launch_handler": { "route_to": "new-client" }.
    • Para usar "capture_links": "existing-client-navigate", adicione: "launch_handler": { "route_to": "existing-client-navigate" }.
    • Para usar "capture_links": "existing-client-event", que nunca foi implementado no teste de origem da captura declarativa de links, adicione: "launch_handler": { "route_to": "existing-client-retain" }. Com essa opção, as páginas no escopo do app não vão mais navegar automaticamente quando uma navegação por link for capturada. Gerencie o LaunchParams em JavaScript chamando window.launchQueue.setConsumer() para ativar a navegação.

O campo capture_links e o registro de teste de origem da captura declarativa de link vão continuar válidos até 30 de março de 2022. Isso garante que os usuários do Chromium 97 e versões anteriores ainda possam iniciar o app da Web em um link capturado.

Para mais detalhes, consulte Controlar como seu app é iniciado.

Feedback

A equipe do Chromium quer saber mais sobre suas experiências com a captura declarativa de links.

Fale sobre o design da API

Há algo na API que não funciona como você esperava? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem alguma dúvida ou comentário sobre o modelo de segurança? Registre um problema de especificação no repositório do GitHub correspondente ou adicione suas ideias a um problema existente.

Informar um problema com a implementação

Você encontrou um bug na implementação do Chromium? Ou a implementação é diferente da especificação? Registre um bug em new.crbug.com. Inclua o máximo de detalhes possível, instruções simples para reprodução e insira UI>Browser>WebAppInstalls na caixa Componentes. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.

Mostrar suporte à API

Você planeja usar a captura de link declarativa? 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 usando a hashtag #DeclarativeLinkCapturing e conte para nós onde e como você está usando a hashtag.

Links úteis

Agradecimentos

A captura declarativa de links foi especificada por Matt Giuca com a contribuição de Alan Cutter e Dominick Ng. Ela foi implementada por Alan Cutter. Este artigo foi revisado por Joe Medley, Matt Giuca, Alan Cutter e Shunya Shishido. Imagem principal de Zulmaury Saavedra no Unsplash (links em inglês).