PWAs como gerenciadores de URLs

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

Thomas Steiner

O que são PWAs como gerenciadores de URL?

Imagine que você está conversando com um amigo usando um aplicativo de mensagens instantâneas, como o Mensagens no macOS, e falando sobre música. Além disso, imagine que vocês dois têm o PWA music.example.com instalado nos seus dispositivos. Se você 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 outro link curto a cada faixa, como 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 para URLs que correspondem a padrões como https://music.example.com, https://*.music.example.com ou https://🎵.example.com. Assim, os links de fora do PWA, por exemplo, de um aplicativo de mensagens instantâneas ou de um cliente de e-mail, serão abertos no PWA instalado, e não em uma guia do navegador.

Os PWA como processadores de URL consistem em duas adições:

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

Casos de uso sugeridos para PWAs como processadores de URL

Exemplos de sites que podem usar essa API incluem:

  • Sites de streaming de música ou vídeo para que links de faixas ou playlists sejam abertos na experiência do player do app.
  • Leitores de notícias ou RSS para que os sites seguidos ou aos quais você se inscreveu sejam abertos no modo leitor do app.

Como usar PWAs como gerenciadores de URL

Ativação por about://flags

Para testar os PWAs como processadores de URL localmente, sem um token de teste de origem, ative a flag #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 pelo membro "url_handlers". Ele aceita uma matriz de objetos com uma propriedade origin, que é um string obrigatório que é um padrão para correspondência de origens. Esses padrões podem ter um prefixo curinga (*) para incluir vários subdomínios (como https://*.example.com). 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 possíveis exemplos, 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 a PWA está em uma origem (music.example.com) diferente de alguns dos URLs que ela 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, e cada objeto representa uma entrada para um app da Web exclusivo. Cada objeto contém:

Campo Descrição Tipo Padrão
"manifest" (Obrigatório) String de 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[] []

Veja abaixo um exemplo de arquivo web-app-origin-association para o exemplo de PWA de música acima. Ele seria hospedado na origem 🎵.example.com e estabeleceria 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 a ser processado 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 pelo arquivo web-app-origin-association correspondente 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 processadores de URL, defina a flag do navegador conforme descrito acima e instale o PWA em https://mandymsft.github.io/pwa/. Ao analisar o manifesto do app da Web, você pode conferir 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 comprovar 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á funcionando, envie uma mensagem de teste para você mesmo usando um 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 abrir na PWA instalada.

O app de mensagens instantâneas do Windows Skype ao lado do PWA de demonstração instalado, que é aberto no modo independente depois de clicar em um link processado por ele em uma mensagem de chat do Skype.

Segurança e permissões

A equipe do Chromium projetou e implementou PWAs como gerenciadores de URL usando os princípios básicos 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 um gerenciador de URL para um determinado padrão de URL, o usuário será solicitado a escolher com qual PWA ele quer processar o padrão, se houver algum. As navegações que começam em uma aba do navegador não são tratadas por essa proposta, que é voltada explicitamente para navegações que começam fora do navegador.

Transparência

Se a validação de associação necessária não puder ser concluída durante a instalação do PWA por qualquer motivo, o navegador não vai registrar o app como um gerenciador de URL ativo para os URLs afetados. Se implementados incorretamente, os gerenciadores de URL podem ser usados para sequestrar 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 processadores 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 aplicativos.

Persistência de permissões

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

Feedback

A equipe do Chromium quer saber sobre suas experiências com os PWAs como processadores de URL.

Fale sobre o design da API

Há algo na API que não funciona como esperado? Ou faltam métodos ou propriedades 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 das especificações? 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 é ótimo para compartilhar reproduções rápidas e fáceis.

Mostrar suporte à API

Você planeja usar PWAs como processadores de URL? Seu apoio público ajuda a equipe do Chromium a priorizar os recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

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

Links úteis

Agradecimentos

PWAs como processadores 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.