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

Thomas Steiner

O que é a captura de link declarativa?

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

Mas a situação fica mais complexa. E se o link aparecer não em um site, mas em uma mensagem de chat que você recebe em um dos apps de chat do Google? Em sistemas operacionais de computador, que têm a noção de janelas de app separadas, se o app já estiver aberto, uma nova janela ou guia precisa ser criada para cada clique no link? Há muitas maneiras de capturar links e navegações, incluindo, mas não se limitando a:

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

Algumas condições especiais, como clicar com o botão do meio do mouse em um link (ou clicar com o botão direito do mouse e selecionar "Abrir em uma nova guia") normalmente não acionam o comportamento de captura de links. Não importa se um link é target=_self ou target=_blank. Assim, os links clicados em uma janela do navegador (ou janela de um PWA diferente) serão 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:

  • PWAs que querem abrir uma janela, em vez de uma guia do navegador, quando o usuário clica em um link para elas. Em um ambiente de computador, geralmente é mais prático 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 focando a instância atual. Os casos de uso secundários incluem:
    • Apps para os quais faz sentido ter apenas uma instância em execução (por exemplo, um player de música ou um jogo).
    • Apps que incluem gerenciamento de vários documentos em uma única instância (por exemplo, uma faixa de guias implementada em HTML).

Como ativar pela página about://flags

Para testar a captura de link declarativa 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 devem ser capturados usando o campo 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 agente do usuário vai escolher o primeiro item compatível na lista, definindo o padrão como "none". Os valores a seguir são compatíveis:

  • "none" (padrão): não há captura de link. Os links clicados que levam a esse escopo de PWA navegam normalmente, sem abrir uma janela de PWA.
  • "new-client": cada link clicado abre uma nova janela de PWA nesse URL.
  • "existing-client-navigate": o link clicado é aberto em uma janela de PWA existente, se disponível, ou em uma nova janela, se não estiver. Se houver mais de uma janela de PWA, o navegador poderá escolher uma delas de forma arbitrária. Ele se comporta como "new-client" se nenhuma janela estiver aberta. 🚨 Cuidado! Essa opção pode levar à perda de dados, já que as páginas podem ser navegadas de forma arbitrária. Os sites precisam saber que estão ativando 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 reprodutores de música. Se a página que está sendo navegada tiver um evento beforeunload, o usuário vai receber o comando antes da conclusão da navegação.

Demonstração

A demonstração da captura de link declarativa consiste em duas demonstrações que interagem entre si:

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

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

Segurança e permissões

A equipe do Chromium projetou e implementou a captura de links declarativa usando os princípios básicos definidos em Como controlar o acesso a recursos poderosos da plataforma da Web, incluindo o controle do usuário, transparência e ergonomia. Essa API permite que os sites tenham novas opções de controle. Primeiro, a capacidade de abrir automaticamente os apps instalados em uma janela. Isso usa a interface atual, mas permite que o site a acione automaticamente. Em segundo lugar, a capacidade de focar uma janela existente no próprio domínio e acionar um evento que contém o URL clicado. O objetivo é permitir que o site navegue de uma janela para uma nova página, substituindo o fluxo de navegação padrão do HTML.

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. Ele será substituído 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, em vez de ser concedida no momento da instalação de um app da Web. Para ativar a captura de links, o usuário precisa iniciar um app instalado no navegador usando Abrir com e escolher Lembrar minha escolha.

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

Os usuários também podem ativar ou desativar a captura de links para um app da Web específico na página de configurações de gerenciamento de apps.

Exemplo de 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.

API Launch Handler

O controle de uma navegação recebida é 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. Para migrar da API Declarative Link Capturing para a API Launch Handler:

  1. Registre seu site para o 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 seu 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 de link declarativa, 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 de link for capturada. Você precisa processar 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 de links declarativos são 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 o app é iniciado.

Feedback

A equipe do Chromium quer saber sobre sua experiência com a captura de links declarativos.

Conte sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem dúvidas ou comentários sobre o modelo de segurança? Envie um problema de especificação no repositório do GitHub correspondente ou adicione sua opinião 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 digite UI>Browser>WebAppInstalls na caixa Components. O Glitch é ótimo para compartilhar reprosagens rápidas e fáceis.

Mostrar suporte para a API

Você planeja usar a captura de links declarativa? 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 #DeclarativeLinkCapturing e informe onde e como você está usando o recurso.

Links úteis

Agradecimentos

A captura de link declarativa foi especificada por Matt Giuca com a contribuição de Alan Cutter e Dominick Ng. A API 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.