PWAs como gerenciadores de URLs

Permita que os PWAs instalados processem URLs para uma experiência mais integrada.

Thomas Steiner

O que são os PWAs como gerenciadores de URL?

Imagine que você está conversando com um amigo usando um app de mensagens instantâneas, como o Mensagens no macOS, e falando sobre música. Imagine também que vocês dois têm o PWA music.example.com instalado nos seus dispositivos. Se quiser compartilhar sua música favorita com um amigo, envie um link direto, como https://music.example.com/rick-astley/never-gonna-give-you-up. Como esse link é muito longo, os desenvolvedores de music.example.com podem ter decidido adicionar um outro link curto a cada faixa, como, por exemplo, https://🎵.example.com/r-a/n-g-g-y-u.

O PWA como gerenciadores de URL permite que apps como music.example.com se registrem como gerenciadores de URLs que correspondem a padrões como https://music.example.com, https://*.music.example.com ou https://🎵.example.com. Assim, links de fora do PWA, por exemplo, de um aplicativo de mensagens instantâneas ou de um cliente de e-mail, são abertos no PWA instalado em vez de em uma guia do navegador.

O PWA como gerenciadores de URL consiste em duas adições:

  1. O membro do manifesto do app da Web "url_handlers".
  2. É o formato de arquivo web-app-origin-association para validar associações de URL dentro e fora do escopo.

Casos de uso sugeridos para PWAs como gerenciadores de URL

Exemplos de sites que podem usar essa API incluem:

  • Sites de streaming de música ou vídeo, portanto, links de faixas ou de playlists são abertos na experiência do player do app.
  • Leitores de notícias ou de RSS enviados ou inscritos em sites são abertos no modo leitor do app.

Como usar PWAs como gerenciadores de URL

Ativando via about://flags

Para testar PWAs como gerenciadores de URLs localmente, sem um token de teste de origem, ative a sinalização #enable-desktop-pwas-url-handling em about://flags.

O membro do manifesto do app da Web "url_handlers"

Para associar um PWA instalado a padrões de URL, esses padrões precisam ser especificados no manifesto do app da Web. Isso acontece com o membro "url_handlers". Ela aceita uma matriz de objetos com uma propriedade origin, que é um string obrigatório que é um padrão para a correspondência de origens. Esses padrões podem ter um prefixo de caractere curinga (*) para incluir vários subdomínios (como https://*.example.com). Os URLs que correspondem a essas origens podem ser processados por esse app da Web. O esquema sempre é considerado https://, mas precisa ser explicitamente mencionado.

O trecho de um manifesto de app da Web abaixo mostra como o exemplo de PWA de música do parágrafo introdutório pode configurar isso. A segunda entrada com o caractere curinga ("https://*.music.example.com") garante que o app também seja ativado para https://www.music.example.com ou outros exemplos em potencial, como https://marketing-activity.music.example.com.

{
  "url_handlers": [
    {
      "origin": "https://music.example.com"
    },
    {
      "origin": "https://*.music.example.com"
    },
    {
      "origin": "https://🎵.example.com"
    }
  ]
}

Arquivo web-app-origin-association

Como o PWA está em uma origem diferente (music.example.com) de alguns dos URLs que ele precisa processar (por exemplo, https://🎵.example.com), o app precisa verificar a propriedade dessas outras origens. Isso acontece em um arquivo web-app-origin-association hospedado nas outras origens.

Esse arquivo precisa conter um JSON válido. A estrutura de nível superior é um objeto, com um membro chamado "web_apps". Esse membro é uma matriz de objetos, em que cada objeto representa uma entrada de um app da Web exclusivo. Cada objeto contém:

Campo Descrição Tipo Padrão
"manifest" (Obrigatório) String do URL do manifesto do app da Web do PWA associado. string N/A
"details" (Opcional) Um objeto que contém matrizes de padrões de URL incluídos e excluídos object N/A

Cada objeto "details" contém:

Campo Descrição Tipo Padrão
"paths" (Opcional) Matriz de strings de caminho permitidas string[] []
"exclude_paths" (Opcional) Matriz de strings de caminho não permitidas string[] []

Confira abaixo um exemplo de arquivo web-app-origin-association para o exemplo de PWA de música acima. Ele ficaria hospedado na origem 🎵.example.com e estabelece a associação com o PWA music.example.com, identificado pelo URL do manifesto do app da Web.

{
  "web_apps": [
    {
      "manifest": "https://music.example.com/manifest.json",
      "details": {
        "paths": ["/*"],
        "exclude_paths": ["/internal/*"]
      }
    }
  ]
}

Quando um URL é correspondente?

Um PWA corresponde a um URL para processamento se as duas condições a seguir forem atendidas:

  • O URL corresponde a uma das strings de origem em "url_handlers".
  • O navegador pode validar, com o respectivo arquivo web-app-origin-association, que cada origem concorda em permitir que esse app processe esse URL.

Sobre a descoberta de arquivos web-app-origin-association

Para que o navegador descubra o arquivo web-app-origin-association, os desenvolvedores precisam colocar o arquivo web-app-origin-association na pasta /.well-known/ na raiz do app. Para que isso funcione, o nome do arquivo precisa ser exatamente web-app-origin-association.

Demonstração

Para testar PWAs como gerenciadores de URL, defina a sinalização do navegador conforme descrito acima e instale o PWA em https://mandymsft.github.io/pwa/ (em inglês). Analisando o manifesto do app da Web, é possível ver que ele processa URLs com os seguintes padrões: https://mandymsft.github.io e https://luhuangmsft.github.io. Como o segundo está em uma origem diferente (luhuangmsft.github.io) do PWA, o PWA em mandymsft.github.io precisa provar a propriedade, o que acontece pelo arquivo web-app-origin-association hospedado em https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Para testar se ele está realmente funcionando, envie uma mensagem de teste para você usando o app de mensagens instantâneas de sua escolha ou um e-mail visualizado em um cliente de e-mail que não seja baseado na Web, como o Mail no macOS. O e-mail ou a mensagem de texto precisa conter um dos links https://mandymsft.github.io ou https://luhuangmsft.github.io. Ambos devem ser abertos no PWA instalado.

O aplicativo de mensagens instantâneas do Windows Skype ao lado do PWA de demonstração instalado, que é aberto no modo autônomo depois de clicar em um link processado por ele em uma mensagem de bate-papo do Skype.

Segurança e permissões

A equipe do Chromium projetou e implementou PWAs como gerenciadores de URL 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.

Controle do usuário

Se mais de um PWA for registrado como gerenciador de URL para um determinado padrão de URL, o usuário vai ser solicitado a escolher com qual PWA ele quer processar o padrão, se houver algum. As navegações que começam em uma guia do navegador não são processadas por essa proposta. Ela é voltada explicitamente para aquelas que começam fora do navegador.

Transparência

Se a validação da associação necessária não for concluída por qualquer motivo durante a instalação do PWA, o navegador não vai registrar o app como um gerenciador ativo de URLs para os URLs afetados. Se implementados incorretamente, eles podem ser usados para invadir o tráfego de sites. É por isso que o mecanismo de associação de apps é uma parte importante do esquema.

Os aplicativos específicos da plataforma já podem usar APIs do sistema operacional para enumerar os aplicativos instalados no sistema do usuário. Por exemplo, os aplicativos no Windows podem usar a API FindAppUriHandlersAsync para enumerar gerenciadores de URL. Se os PWAs forem registrados como gerenciadores de URL no nível do SO no Windows, a presença deles será visível para outros apps.

Persistência da permissão

Uma origem pode modificar as associações com PWAs a qualquer momento. Os navegadores vão tentar regularmente revalidar as associações dos apps da Web instalados. Se o registro de um gerenciador de URL não for validado porque os dados da associação mudaram ou não estão mais disponíveis, o navegador vai remover os registros.

Feedback

A equipe do Chromium quer saber mais sobre suas experiências com os PWAs como gerenciadores de URLs.

Fale sobre o design da API

Algo na API 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 PWAs como gerenciadores de URL? Seu suporte público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegador a importância do suporte a eles.

Envie um tweet para @ChromiumDev usando a hashtag #URLHandlers e informe onde e como você está usando a hashtag.

Links úteis

Agradecimentos

Os PWAs como gerenciadores de URL foram especificados e implementados por Lu Huang e Mandy Chen da equipe do Microsoft Edge. Este artigo foi revisado por Joe Medley. Imagem principal de Bryson Hammer no Unsplash (links em inglês).