PWAs como gerenciadores de URLs

Permita que os PWAs instalados processem URLs para 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 vocês estão falando sobre música. Imagine também que vocês dois têm o PWA do music.example.com instalado nos 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 do music.example.com podem ter decidido adicionar um link curto a cada faixa, como, por exemplo, https://🎵.example.com/r-a/n-g-g-y-u.

O PWA como gerenciador de URLs permite que apps como o 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, 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 do arquivo web-app-origin-association para validar associações de URLs dentro e fora do escopo.

Casos de uso sugeridos para PWAs como gerenciadores de URL

Exemplos de sites que podem usar essa API:

  • Sites de streaming de música ou vídeo para que os links de músicas ou playlists sejam abertos na experiência do player do app.
  • Leitores de notícias ou RSS para que os sites seguidos ou assinados sejam abertos no modo de leitura do app.

Como usar PWAs como gerenciadores de URL

Ativar com about://flags

Para testar os PWAs como gerenciadores 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 do URL, eles 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 é uma string obrigatória que é um padrão para corresponder origens. Esses padrões podem ter um prefixo 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 mencionado explicitamente.

O trecho a seguir de um manifesto de app da Web 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, 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 do 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 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 corresponde?

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 usar o respectivo arquivo web-app-origin-association para validar que cada origem concorda em permitir que o 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 flag do navegador conforme descrito e instale o PWA em https://mandymsft.github.io/pwa/. Ao analisar 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 último está em uma origem diferente (luhuangmsft.github.io) do PWA, o PWA em mandymsft.github.io precisa comprovar a propriedade, o que acontece usando o arquivo web-app-origin-association hospedado em https://luhuangmsft.github.io/.well-known/web-app-origin-association.

Para testar se está funcionando, envie uma mensagem de teste para você usando um app de mensagens instantâneas da 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 os links https://mandymsft.github.io ou https://luhuangmsft.github.io. Ambos devem ser abertos no PWA instalado.

O app de mensagens instantâneas do Skype para Windows 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 se registrar como um gerenciador de URL para um determinado padrão do URL, o usuário será solicitado a escolher com qual PWA quer processar o padrão, se houver. As navegações que começam em uma guia do navegador não são processadas por essa proposta, que é explicitamente voltada 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 forem implementados incorretamente, os gerenciadores de URL podem ser usados para sequestrar o tráfego de sites. Por isso, 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 se registrarem 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 um registro de gerenciador 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 gerenciadores de URL.

Fale sobre o design da API

Há algo na API que não funciona como você esperava? Ou faltam métodos ou propriedades para implementar sua ideia? Tem alguma pergunta 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 atual.

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 para reprodução e insira UI>Browser>WebAppInstalls na caixa Components.

Mostrar suporte para a API

Você planeja usar PWAs como gerenciadores de URL? Seu apoio público ajuda a equipe do Chromium a priorizar recursos e mostra a outros fornecedores de navegadores como é importante oferecer suporte a eles.

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

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 documento foi revisado por Joe Medley.